webs-sdk 0.19.62 → 0.19.65

package/docs/FOR_YOU_360_FACESWAP_FIX.md

@@ -0,0 +1,400 @@
+# CreativeFaceSwap — Ajustes necesarios en 360vrtube
+
+> **SDK v0.18.83+** requerido  
+> Afecta al componente `creativeFaceSwap` dentro de `ForYouPage`
+
+---
+
+## Contexto
+
+En `v0.18.83` se han corregido dos bugs del componente `CreativeFaceSwap` que se manifestaban
+en el proyecto 360vrtube:
+
+| # | Síntoma | Causa |
+|---|---------|-------|
+| Bug 1 | Los ejemplos del carrusel izquierdo no se muestran | `contentsConfig` no estaba conectado al componente |
+| Bug 2 | `"Unexpected token '<'..."` al pulsar CREATE | El endpoint devuelve HTML (404/500) en lugar de JSON |
+
+Ambos bugs requieren **cambios en el proyecto 360vrtube** además de actualizar el SDK.
+
+---
+
+## Paso 1 — Actualizar el SDK
+
+```bash
+npm install webs-sdk@0.18.83
+# o
+yarn add webs-sdk@0.18.83
+```
+
+---
+
+## Paso 2 — Bug 1: conectar los ejemplos con `contentsConfig`
+
+### ¿Qué cambia?
+
+Antes se pasaba `config.contents[]` dentro del objeto `config` de la feature. Eso funciona para
+cargar el **listado** del componente principal (generate), pero **no tiene efecto** en los
+ejemplos del carrusel. Ahora hay una prop específica para ello: **`contentsConfig`**.
+
+### Cómo debe quedar la config en 360vrtube
+
+```tsx
+// ❌ ANTES — los ejemplos no se cargan
+creativeFaceSwap: {
+  card: {
+    desktopImage: '/images/faceswap-card.jpg',
+    ctaColor: '#FF5500',
+  },
+  config: {
+    userId: USER_ID,
+    userLogin: USER_LOGIN,
+    wid: WEBSITE_ID,
+    apiEndpoints: {
+      generate: '/api/face-swap/generate',
+      progress: '/api/face-swap/progress',
+      getImage:  '/api/face-swap/get-image',
+    },
+  },
+  // ← antes se intentaba pasar contents aquí dentro, no funciona
+}
+
+// ✅ AHORA — usar contentsConfig para los ejemplos
+creativeFaceSwap: {
+  card: {
+    desktopImage: '/images/faceswap-card.jpg',
+    ctaColor: '#FF5500',
+  },
+  config: {
+    userId: USER_ID,
+    userLogin: USER_LOGIN,
+    wid: WEBSITE_ID,
+    apiEndpoints: {
+      generate: '/api/face-swap/generate',
+      progress: '/api/face-swap/progress',
+      getImage:  '/api/face-swap/get-image',
+    },
+  },
+  // ← prop nueva: carga los ejemplos del carrusel izquierdo
+  contentsConfig: {
+    apiBaseUrl: 'https://api.360vrtube.com',   // ← ajustar a la URL real
+    locale: 'en',
+    website_id: WEBSITE_ID,
+    contents: [
+      {
+        preset: 'getGlobalContentsByIDs',
+        includeIds: [104557, 100180, 98423, 97811],  // ← IDs de tus ejemplos
+      },
+      // también puedes combinar con tags:
+      // { preset: 'getGlobalContentsByTags', tags: ['faceswap-examples'] },
+    ],
+  },
+}
+```
+
+### Alternativa: tag simple
+
+Si los ejemplos están en un solo tag sin necesidad de IDs concretos:
+
+```tsx
+contentsConfig: {
+  apiBaseUrl: 'https://api.360vrtube.com',
+  locale: 'en',
+  tags: 'faceswap-examples',   // ← tag de los ejemplos en vuestro CMS
+},
+```
+
+### Prioridad de ejemplos
+
+El SDK aplica este orden de prioridad (el primero que tenga datos gana):
+
+```
+1. examples[]  (array estático pasado directamente)
+2. contentsConfig  (fetch interno — NUEVO)
+3. examplesTag  (fetch simple por tag dentro del componente)
+```
+
+### Qué debe tener cada item en el CMS para que aparezca como ejemplo
+
+El SDK mapea los items recibidos a `FaceSwapExample` de la siguiente forma:
+
+| Campo del item | Se usa como |
+|----------------|-------------|
+| `thumbnail` | Imagen del ejemplo en el carrusel |
+| `images.img1` | Imagen del ejemplo (fallback si no hay thumbnail) |
+| `imageUrl` | Imagen del ejemplo (segundo fallback) |
+| `title` | Descripción debajo de la imagen |
+| `description` | Descripción (fallback si no hay title) |
+
+> ⚠️ Si el item no tiene imagen (`thumbnail`, `images.img1` ni `imageUrl`), **se descarta**
+> y no aparecerá en el carrusel.
+
+---
+
+## Paso 3 — Bug 2: crear las rutas API del endpoint generate
+
+### ¿Qué ocurría?
+
+Al pulsar el botón **CREATE**, el SDK llamaba a `/api/face-swap/generate` (u otra ruta).
+Si esa ruta no existe en el proyecto Next.js, el servidor devuelve una página HTML de 404
+en lugar de JSON. El SDK intentaba `response.json()` sobre ese HTML y crasheaba con:
+
+```
+SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
+```
+
+### Fix en el SDK (ya incluido en v0.18.83)
+
+El SDK ahora detecta el `Content-Type` de la respuesta antes de parsear. Si no es JSON,
+muestra un mensaje de error claro en la UI:
+
+```
+HTTP 404: The generate endpoint returned an unexpected response.
+Check that the API route exists and is correctly configured in this project.
+```
+
+### Acción requerida en 360vrtube: crear las rutas API
+
+Necesitáis crear **tres rutas API** en el proyecto Next.js que hagan de proxy hacia vuestro
+servicio de generación de imágenes. El SDK llama a estas rutas directamente (son `config.apiEndpoints`).
+
+#### App Router (`app/api/...`)
+
+**`app/api/face-swap/generate/route.ts`**
+
+```ts
+import { NextRequest, NextResponse } from 'next/server'
+
+const FACESWAP_API = process.env.FACESWAP_API_URL // ← URL interna del servicio
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json()
+    const upstream = await fetch(`${FACESWAP_API}/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    const data = await upstream.json()
+    return NextResponse.json(data, { status: upstream.status })
+  } catch (err) {
+    console.error('[face-swap/generate]', err)
+    return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 })
+  }
+}
+```
+
+**`app/api/face-swap/progress/route.ts`**
+
+```ts
+import { NextRequest, NextResponse } from 'next/server'
+
+const FACESWAP_API = process.env.FACESWAP_API_URL
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json()
+    const upstream = await fetch(`${FACESWAP_API}/progress`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    const data = await upstream.json()
+    return NextResponse.json(data, { status: upstream.status })
+  } catch (err) {
+    console.error('[face-swap/progress]', err)
+    return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 })
+  }
+}
+```
+
+**`app/api/face-swap/get-image/route.ts`**
+
+```ts
+import { NextRequest, NextResponse } from 'next/server'
+
+const FACESWAP_API = process.env.FACESWAP_API_URL
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json()
+    const upstream = await fetch(`${FACESWAP_API}/get-image`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    const data = await upstream.json()
+    return NextResponse.json(data, { status: upstream.status })
+  } catch (err) {
+    console.error('[face-swap/get-image]', err)
+    return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 })
+  }
+}
+```
+
+#### Pages Router (`pages/api/...`) — si el proyecto usa Pages Router
+
+```ts
+// pages/api/face-swap/generate.ts
+import type { NextApiRequest, NextApiResponse } from 'next'
+
+const FACESWAP_API = process.env.FACESWAP_API_URL
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'POST') return res.status(405).end()
+  try {
+    const upstream = await fetch(`${FACESWAP_API}/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(req.body),
+    })
+    const data = await upstream.json()
+    res.status(upstream.status).json(data)
+  } catch {
+    res.status(500).json({ success: false, error: 'Internal server error' })
+  }
+}
+```
+
+Repetir el mismo patrón para `progress.ts` y `get-image.ts`.
+
+### Variable de entorno
+
+Añadir al `.env.local`:
+
+```bash
+FACESWAP_API_URL=https://tu-servicio-faceswap.com   # URL del servicio real
+```
+
+---
+
+## Paso 4 — Configuración completa de referencia
+
+Este es el bloque final con los dos fixes aplicados:
+
+```tsx
+import { ForYouPage } from 'webs-sdk'
+import type { ForYouFeatures } from 'webs-sdk'
+
+const features: ForYouFeatures = {
+  creativeFaceSwap: {
+    card: {
+      desktopImage: '/images/faceswap-card-desktop.jpg',
+      mobileImage:  '/images/faceswap-card-mobile.jpg',
+      ctaColor: '#FF5500',
+      backgroundColor: '#F9F9F9',
+    },
+
+    // Endpoints de generación — rutas API del proyecto
+    config: {
+      userId:    USER_ID,
+      userLogin: USER_LOGIN,
+      wid:       WEBSITE_ID,
+      apiEndpoints: {
+        generate: '/api/face-swap/generate',   // POST → crea el job
+        progress: '/api/face-swap/progress',   // POST → polling del progreso
+        getImage: '/api/face-swap/get-image',  // POST → obtiene la imagen final
+      },
+    },
+
+    // Ejemplos del carrusel izquierdo — Bug 1 fix
+    contentsConfig: {
+      apiBaseUrl: 'https://api.360vrtube.com',
+      locale: 'en',
+      website_id: WEBSITE_ID,
+      contents: [
+        {
+          preset: 'getGlobalContentsByIDs',
+          includeIds: [104557, 100180, 98423],  // ← IDs reales de los ejemplos
+        },
+      ],
+    },
+
+    // Textos opcionales (override sobre los del SDK)
+    texts: {
+      uploadTitle: 'Your photo',
+      createButton: 'GENERATE',
+      examplesTitle: 'Try these examples',
+    },
+
+    // Callbacks opcionales
+    onGenerationComplete: (imageUrl) => {
+      console.log('Generated:', imageUrl)
+    },
+    onError: (error) => {
+      console.error('FaceSwap error:', error)
+    },
+  },
+
+  // ... resto de features
+}
+
+export default function ForYouSection() {
+  return (
+    <ForYouPage
+      locale="en"
+      features={features}
+    />
+  )
+}
+```
+
+---
+
+## Checklist de verificación
+
+Antes de hacer deploy, verificar:
+
+- [ ] SDK actualizado a `v0.18.83` o superior (`npm ls webs-sdk`)
+- [ ] `contentsConfig` añadido con los IDs o tags correctos de los ejemplos
+- [ ] Los items del CMS tienen `thumbnail` o imagen equivalente
+- [ ] Ruta `/api/face-swap/generate` existe y responde `{ success: true, data: { md5, i_jobs } }`
+- [ ] Ruta `/api/face-swap/progress` existe y responde `{ success: true, data: { pct: 0-100 } }`
+- [ ] Ruta `/api/face-swap/get-image` existe y responde `{ success: true, data: { s3_image: '...' } }`
+- [ ] Variable de entorno `FACESWAP_API_URL` configurada en `.env.local` y en producción
+- [ ] El carrusel de ejemplos se muestra con imágenes al abrir la feature
+- [ ] Al pulsar CREATE con foto + descripción, el proceso arranca sin errores
+
+---
+
+## Respuesta esperada de cada endpoint
+
+El SDK espera estas estructuras JSON. Si el servicio devuelve algo diferente,
+hay que adaptar la ruta proxy para transformar la respuesta.
+
+### `/generate`
+```json
+{
+  "success": true,
+  "data": {
+    "md5": "abc123def456",
+    "i_jobs": 1
+  }
+}
+```
+
+### `/progress`
+```json
+{
+  "success": true,
+  "data": {
+    "pct": 45
+  }
+}
+```
+
+### `/get-image`
+```json
+{
+  "success": true,
+  "data": {
+    "s3_image": "https%3A%2F%2Fcdn.example.com%2Fresult.jpg"
+  }
+}
+```
+
+> Nota: `s3_image` debe estar **URL-encoded**. El SDK aplica `decodeURIComponent()` internamente.
+
+---
+
+*Generado automáticamente por el SDK — webs_sdk v0.18.83 — 2026-06-30*