webs-sdk 0.19.62 → 0.19.65

package/docs/FOR_YOU_SDK_WALLPAPERSNAME_BUG.md

@@ -0,0 +1,106 @@
+# Bug Report: `ForYouPage` — `wallpapersName` feature shows "No wallpapers available"
+
+## Summary
+
+When `wallpapersName` is rendered inside `ForYouPage`, it always shows "No wallpapers available" even though the standalone `WallpapersNamePage` component works correctly with the same data.
+
+---
+
+## Environment
+
+- **SDK version:** 0.18.74
+- **Component:** `ForYouPage` → feature `wallpapersName`
+- **Affected URL:** `/en/foryou-fullpage?feature=wallpapersName`
+- **Working URL:** `/en/for-you-templates` (uses `WallpapersNamePage` directly)
+
+---
+
+## Root cause
+
+`ForYouPage` internally passes the feature config to `WallpapersName` using the **generic keys** (`tags`, `website_id`), but the `WallpapersName` component expects **specific keys** (`wallpaperTag`, `wid`).
+
+### What `WallpapersName` expects
+
+```ts
+config: {
+  apiUrl: '/api/get_contents_by_tags',
+  wallpaperTag: 'wogcawallpapers',   // ← specific key: string
+  locale: 'en',
+  wid: '42',                          // ← specific key
+}
+```
+
+### What `ForYouPage` currently passes to `WallpapersName`
+
+```ts
+config: {
+  apiUrl: '/api/get_contents_by_tags',
+  tags: ['wogcawallpapers'],          // ← generic key: string[]  ❌
+  locale: 'en',
+  website_id: '42',                   // ← generic key            ❌
+}
+```
+
+Because `wallpaperTag` is `undefined`, the component calls the API without a tag filter and receives no results.
+
+---
+
+## Comparison: standalone vs. ForYouPage
+
+| | `WallpapersNamePage` (standalone) | `ForYouPage` → `wallpapersName` |
+|---|---|---|
+| Tag key | `wallpaperTag` ✅ | `tags` ❌ |
+| Website ID key | `wid` ✅ | `website_id` ❌ |
+| Result | Works correctly | "No wallpapers available" |
+
+---
+
+## Expected behavior
+
+`ForYouPage` should normalize the generic config keys when rendering the `wallpapersName` case, just like it already does for other features:
+
+- `ringtone`: normalizes `tags` → `ringtoneTag` (already fixed in 0.18.72)
+- `memeGenerator`: normalizes `tags` → `memeTag` (already fixed in 0.18.72)
+- `wallpapersName`: **missing normalization** — `tags` → `wallpaperTag` and `website_id` → `wid`
+
+---
+
+## Requested fix
+
+In the `ForYouPage` internal handler for the `wallpapersName` case, apply the same normalization pattern used for `ringtone` and `memeGenerator`:
+
+```ts
+// Inside ForYouPage — case 'wallpapersName'
+const wallpaperTag =
+  config.wallpaperTag ||
+  (Array.isArray(config.tags) ? config.tags[0] : config.tags) ||
+  'wallpaper_name';
+
+const wid = config.wid || config.website_id || '';
+
+// Pass to WallpapersName component:
+// { apiUrl, wallpaperTag, wid, locale, ... }
+```
+
+---
+
+## Workaround (project-side, until SDK fix)
+
+Until the SDK is fixed, `ForYouFullPageView.tsx` passes `wallpaperTag` and `wid` directly for the `WallpapersName` feature:
+
+```ts
+if (item.key === 'WallpapersName') {
+  baseConfig.wallpaperTag = tags[0] ?? 'wogcawallpapers';
+  baseConfig.wid = website_id;
+  delete baseConfig.tags;
+  delete baseConfig.website_id;
+}
+```
+
+This workaround is not ideal because `ForYouPage` should abstract away these config differences internally.
+
+---
+
+## Priority
+
+**High** — `wallpapersName` is a core feature of the ForYou hub and it is completely broken inside `ForYouPage`.

package/docs/FOR_YOU_WALLPAPERSNAME_ENHANCEMENT_PLAN.md

@@ -0,0 +1,210 @@
+# Plan: WallpapersName feature enhancement in ForYouPage
+
+## Context
+
+`ForYouPage` (SDK) renders the `wallpapersName` feature using the `WallpapersName` component internally.
+The current `WallpapersNameFeatureOverride` type exposes a `config` prop that only partially maps to what
+the underlying component needs. The goal of this plan is to:
+
+1. Allow the call to `get_contents_by_tags` to be fully configurable per portal from `product_config`.
+2. Support a `content_default_enabled: true` flag that activates a curated set of default items even when
+   the portal-specific API call returns empty results.
+3. Ensure that the breadcrumb rendered inside `WallpapersName` reflects the configured content source.
+
+---
+
+## Current state
+
+### SDK type — `WallpapersNameFeatureOverride`
+
+```ts
+export interface WallpapersNameFeatureOverride {
+  card?: ForYouCardVisual;
+  theme?: Partial<WallpapersNameTheme>;
+  texts?: Partial<WallpapersNameTexts>;
+  config?: ForYouFeatureConfig & {
+    wid?: string;
+  };
+  items?: WallpapersNameItem[];
+  categories?: WallpapersNameCategory[];
+  howItWorksSteps?: WallpapersNameHowItWorksStep[];
+  showEmptyState?: boolean;
+  onCustomise?: (item: WallpapersNameItem) => void;
+}
+```
+
+### SDK type — `ForYouFeatureConfig`
+
+```ts
+export interface ForYouFeatureConfig {
+  apiUrl?: string;
+  apiBaseUrl?: string;
+  tags?: string | string[];
+  locale?: string;
+  website_id?: string;
+  initialCount?: number;
+  loadMoreCount?: number;
+  contents?: ForYouContentPreset[];
+}
+```
+
+### What the underlying `WallpapersName` component expects
+
+```ts
+config: {
+  apiUrl: string;
+  wallpaperTag?: string;   // single string — normalized by SDK from tags[0]
+  locale?: string;
+  initialCount?: number;
+  loadMoreCount?: number;
+  wid?: string;            // normalized by SDK from website_id
+}
+```
+
+### What `ForYouPage` internally does (SDK v0.18.75)
+
+The SDK already normalizes:
+- `tags[0]` → `wallpaperTag`
+- `website_id` → `wid`
+
+It does NOT yet support:
+- Passing multiple content sources (tabs by tag) to `WallpapersName`
+- A `content_default_enabled` fallback mechanism
+- Breadcrumb configuration passthrough
+
+---
+
+## Proposed changes
+
+### 1. Extend `WallpapersNameFeatureOverride.config` in the SDK
+
+Add the following fields to the config shape accepted by the `wallpapersName` case inside `ForYouPage`:
+
+```ts
+config?: ForYouFeatureConfig & {
+  wid?: string;
+  wallpaperTag?: string;         // explicit tag override (skips normalization from tags[])
+  content_default_enabled?: boolean;  // NEW — activates built-in default items as fallback
+  defaultItems?: WallpapersNameItem[]; // NEW — optional explicit list of fallback items
+};
+```
+
+#### Behavior of `content_default_enabled`
+
+| Scenario | Behavior |
+|---|---|
+| API returns items | Show API items only (normal flow) |
+| API returns 0 items AND `content_default_enabled: true` | Show `defaultItems` (if provided) OR SDK built-in curated set |
+| API returns 0 items AND `content_default_enabled: false` or absent | Show empty state |
+
+The SDK built-in curated set is a small static array of ~8 public-domain wallpapers stored inside
+`ForYouPage.js` used only as last-resort fallback. Projects can override this via `defaultItems`.
+
+### 2. Breadcrumb configuration passthrough
+
+`WallpapersName` does not currently expose a `breadcrumbItems` prop (unlike `Wallpapers`).
+The plan is to add it:
+
+```ts
+// in WallpapersNameProps (WallpapersName.d.ts)
+breadcrumbItems?: { label: string; href?: string }[];
+
+// in WallpapersNameFeatureOverride (ForYouPage.d.ts)
+breadcrumbItems?: { label: string; href?: string }[];
+```
+
+When `WallpapersName` is rendered inside `ForYouPage`, the SDK should:
+1. Check if `breadcrumbItems` is provided in the feature override.
+2. If provided, pass it through to `WallpapersName`.
+3. If NOT provided, auto-generate breadcrumbs based on the `locale`:
+   ```
+   ForYou > WallpapersName
+   ```
+   using the SDK's own i18n translations.
+
+### 3. Project-side changes in `ForYouFullPageView.tsx`
+
+Once the SDK changes are shipped, `ForYouFullPageView.tsx` should be updated to pass the new config:
+
+```ts
+if (item.key === 'WallpapersName') {
+  // existing
+  featureEntry.howItWorksSteps = [ /* ... */ ];
+
+  // new — read from product_config or use defaults
+  const wallpaperTag = tags[0] ?? 'wogcawallpapers';
+  featureEntry.config = {
+    ...featureEntry.config,
+    wallpaperTag,
+    content_default_enabled: (item.contents?.[0] as any)?.content_default_enabled ?? false,
+  };
+
+  // optional: pass breadcrumb
+  featureEntry.breadcrumbItems = [
+    { label: t('for_you.breadcrumb.for_you'), href: `/${locale}/foryou-fullpage` },
+    { label: t('for_you.wallpapers_name_component.breadcrumb_label') },
+  ];
+}
+```
+
+### 4. `product_config` schema for `WallpapersName` item
+
+Each portal can configure the feature via its `product_config.sections[foryou].items`:
+
+```json
+{
+  "key": "WallpapersName",
+  "contents": [
+    {
+      "tags": ["wogcawallpapers"],
+      "content_default_enabled": true
+    }
+  ]
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `tags` | `string[]` | Yes | API tag used for `wallpaperTag`. First element is used. |
+| `content_default_enabled` | `boolean` | No (default `false`) | Activates fallback default items when API returns empty. |
+
+---
+
+## Implementation order
+
+### Phase 1 — SDK changes (webs-sdk)
+
+1. **`WallpapersName.tsx`**: Add `breadcrumbItems` prop. Render breadcrumb when provided.
+2. **`WallpapersName.d.ts`**: Export updated type with `breadcrumbItems`.
+3. **`ForYouPage.tsx`** — case `wallpapersName`:
+   - Accept `config.content_default_enabled` and `config.defaultItems`.
+   - When API resolves with 0 items and `content_default_enabled === true`, merge in `defaultItems`
+     or the SDK built-in curated set.
+   - Pass `breadcrumbItems` from the feature override to `WallpapersName`.
+4. **`ForYouPage.d.ts`**: Update `WallpapersNameFeatureOverride` with the new fields.
+5. **Publish** new SDK version (suggested: `0.18.76`).
+
+### Phase 2 — Project changes (winsports)
+
+1. **`ForYouFullPageView.tsx`**: Read `content_default_enabled` from `itemConfig.contents[0]` and
+   pass it through the `featureEntry.config`. Add `breadcrumbItems`.
+2. **`product_config`** (portal backend): Add `content_default_enabled: true` to the `WallpapersName`
+   item for portals that should show default content on empty results.
+
+---
+
+## Expected result per URL
+
+| URL | Before | After |
+|---|---|---|
+| `/foryou-fullpage?feature=wallpapersName` | No "How does it work?", button blocked when API empty | Shows steps, button active when API has data, fallback items shown when API empty + flag enabled |
+| `/for-you-templates` | Shows `WallpapersName` + `AETemplatesSection` together | Shows only `AETemplatesSection` (already fixed) |
+
+---
+
+## Open questions
+
+- Should `defaultItems` be defined per-locale in the SDK, or is one global list sufficient?
+- Should the breadcrumb be hidden (`hideBreadcrumb: true`) when `WallpapersName` is inside `ForYouPage`
+  and the hub already handles navigation? Currently `WallpapersName` has no `hideBreadcrumb` prop
+  (unlike `Wallpapers`). This should also be added in Phase 1.

package/docs/LEGAL_USAGE.md

@@ -0,0 +1,190 @@
+# Legal Manager - Guía de Uso
+
+El **LegalManager** es una librería del `webs-sdk` que permite obtener textos legales (Términos y Condiciones, Política de Privacidad, Política de Cookies) desde la API de Fluver-AI.
+
+## Instalación
+
+El LegalManager está incluido automáticamente en el `webs-sdk`. Solo necesitas importar el SDK:
+
+```typescript
+import WebsSDK from 'webs-sdk';
+```
+
+## Uso Básico
+
+### Obtener Términos y Condiciones
+
+```typescript
+try {
+    const termsAndConditions = await WebsSDK.Legal.getLegalText(
+        'mi-web-id',  // ID de tu sitio web
+        'tc',         // Tipo: 'tc' (Terms & Conditions)
+        'es'          // Idioma (opcional, por defecto 'es')
+    );
+    
+    console.log(termsAndConditions);
+    // {
+    //   success: true,
+    //   data: { ... contenido legal ... },
+    //   website_id: 'mi-web-id',
+    //   type: 'tc',
+    //   language: 'es'
+    // }
+} catch (error) {
+    console.error('Error al obtener términos y condiciones:', error);
+}
+```
+
+### Obtener Política de Privacidad
+
+```typescript
+try {
+    const privacyPolicy = await WebsSDK.Legal.getLegalText(
+        'mi-web-id',
+        'privacy',    // Tipo: 'privacy'
+        'en'          // Idioma inglés
+    );
+    
+    console.log(privacyPolicy.data);
+} catch (error) {
+    console.error('Error al obtener política de privacidad:', error);
+}
+```
+
+### Obtener Política de Cookies
+
+```typescript
+try {
+    const cookiePolicy = await WebsSDK.Legal.getLegalText(
+        'mi-web-id',
+        'cookies'     // Tipo: 'cookies'
+        // Sin especificar idioma, usa 'es' por defecto
+    );
+    
+    console.log(cookiePolicy.data);
+} catch (error) {
+    console.error('Error al obtener política de cookies:', error);
+}
+```
+
+## API Reference
+
+### `getLegalText(website_id, type, language?)`
+
+Obtiene el texto legal especificado desde la API.
+
+**Parámetros:**
+
+- `website_id` (string, requerido): El identificador único de tu sitio web
+- `type` (LegalDocumentType, requerido): El tipo de documento legal
+  - `'tc'` - Términos y Condiciones (Terms & Conditions)
+  - `'privacy'` - Política de Privacidad
+  - `'cookies'` - Política de Cookies
+- `language` (string, opcional): Código del idioma (por defecto: `'es'`)
+  - Ejemplos: `'es'`, `'en'`, `'fr'`, `'de'`, etc.
+
+**Retorna:**
+
+Una `Promise` que resuelve con un objeto `LegalTextResponse`:
+
+```typescript
+interface LegalTextResponse {
+    success: boolean;
+    data: any;           // Contenido del documento legal
+    website_id: string;
+    type: string;
+    language: string;
+}
+```
+
+**Excepciones:**
+
+Lanza un error si:
+- La petición a la API falla
+- El website_id o type no son válidos
+- No hay conexión de red
+
+## Ejemplos de Uso Completos
+
+### Ejemplo 1: Mostrar T&C en una página web
+
+```typescript
+async function displayTermsAndConditions() {
+    try {
+        const response = await WebsSDK.Legal.getLegalText('my-website', 'tc', 'es');
+        
+        if (response.success) {
+            const contentDiv = document.getElementById('legal-content');
+            contentDiv.innerHTML = response.data.content;
+        }
+    } catch (error) {
+        console.error('No se pudieron cargar los términos:', error);
+        alert('Error al cargar los términos y condiciones');
+    }
+}
+```
+
+### Ejemplo 2: Selector de idioma para documentos legales
+
+```typescript
+async function loadLegalDocument(type: 'tc' | 'privacy' | 'cookies', language: string) {
+    const website_id = 'mi-sitio-web';
+    
+    try {
+        const response = await WebsSDK.Legal.getLegalText(website_id, type, language);
+        
+        return response.data;
+    } catch (error) {
+        console.error(`Error cargando documento ${type} en ${language}:`, error);
+        return null;
+    }
+}
+
+// Uso
+const spanishTC = await loadLegalDocument('tc', 'es');
+const englishPrivacy = await loadLegalDocument('privacy', 'en');
+const frenchCookies = await loadLegalDocument('cookies', 'fr');
+```
+
+### Ejemplo 3: Cache de documentos legales
+
+```typescript
+class LegalDocumentCache {
+    private cache: Map<string, any> = new Map();
+    
+    async getLegalDocument(
+        website_id: string, 
+        type: 'tc' | 'privacy' | 'cookies', 
+        language: string = 'es'
+    ) {
+        const cacheKey = `${website_id}-${type}-${language}`;
+        
+        // Verificar si está en cache
+        if (this.cache.has(cacheKey)) {
+            console.log('Retornando desde cache');
+            return this.cache.get(cacheKey);
+        }
+        
+        // Obtener desde API
+        try {
+            const response = await WebsSDK.Legal.getLegalText(website_id, type, language);
+            
+            if (response.success) {
+                this.cache.set(cacheKey, response.data);
+                return response.data;
+            }
+        } catch (error) {
+            console.error('Error obteniendo documento legal:', error);
+            throw error;
+        }
+    }
+    
+    clearCache() {
+        this.cache.clear();
+    }
+}
+
+// Uso
+const legalCache = new LegalDocumentCache();
+const terms = await legalCache.getLegalDocument('my-site', 'tc', 'es');
+```