webs-sdk 0.19.64 → 0.19.65

package/public/spin2win/fonts/switzer/README.md

@@ -1,23 +1,23 @@
-# Instrucciones para agregar la fuente Switzer
-
-## 📁 Archivos necesarios
-
-Copia los siguientes archivos de la fuente Switzer a esta carpeta:
-
-### Archivos requeridos:
-- `Switzer-Regular.woff2`
-- `Switzer-Regular.woff`
-- `Switzer-Medium.woff2`
-- `Switzer-Medium.woff`
-- `Switzer-Semibold.woff2`
-- `Switzer-Semibold.woff`
-- `Switzer-Bold.woff2`
-- `Switzer-Bold.woff`
-
-## 📝 Notas:
-- Los archivos .woff2 son la versión comprimida (más eficiente)
-- Los archivos .woff son la versión de respaldo para navegadores antiguos
-- La configuración de @font-face ya está lista en `spin2win/styles/fonts.css`
-
-## ✅ Una vez copiados los archivos:
+# Instrucciones para agregar la fuente Switzer
+
+## 📁 Archivos necesarios
+
+Copia los siguientes archivos de la fuente Switzer a esta carpeta:
+
+### Archivos requeridos:
+- `Switzer-Regular.woff2`
+- `Switzer-Regular.woff`
+- `Switzer-Medium.woff2`
+- `Switzer-Medium.woff`
+- `Switzer-Semibold.woff2`
+- `Switzer-Semibold.woff`
+- `Switzer-Bold.woff2`
+- `Switzer-Bold.woff`
+
+## 📝 Notas:
+- Los archivos .woff2 son la versión comprimida (más eficiente)
+- Los archivos .woff son la versión de respaldo para navegadores antiguos
+- La configuración de @font-face ya está lista en `spin2win/styles/fonts.css`
+
+## ✅ Una vez copiados los archivos:
 La fuente Switzer estará disponible automáticamente para el tema `womantoday`.

package/scripts/install-agent-skill.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+
+// Copy the portable Agent Skills bundle into a consuming project.
+// JavaScript is used because published CLI entry points must run on Node without TS tooling.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('Usage: webs-sdk-skill [--force]\nInstall skill into .agents/skills/webs-sdk-package in the current directory.');
+  process.exit(0);
+}
+if (args.some((arg) => arg !== '--force')) {
+  console.error('Unknown option. Use webs-sdk-skill --help.');
+  process.exit(2);
+}
+
+const source = path.resolve(__dirname, '..', 'skills', 'webs-sdk-package');
+const target = path.resolve(process.cwd(), '.agents', 'skills', 'webs-sdk-package');
+if (!fs.existsSync(path.join(source, 'SKILL.md'))) {
+  console.error('Package is missing its agent skill.');
+  process.exit(1);
+}
+if (fs.existsSync(target)) {
+  if (!args.includes('--force')) {
+    console.error(`Skill already exists at ${target}. Run webs-sdk-skill --force to replace it.`);
+    process.exit(1);
+  }
+  fs.rmSync(target, { recursive: true, force: true });
+}
+fs.mkdirSync(path.dirname(target), { recursive: true });
+fs.cpSync(source, target, { recursive: true });
+console.log(`Installed webs-sdk skill at ${target}`);

package/skills/webs-sdk-package/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: webs-sdk-package
+description: Use the webs-sdk npm package in Nexum portals. Activate when choosing or integrating reusable SDK functionality: authentication, sessions, tracking, consent, AI content components, For You, Streak, quiz, esports, Radix UI, VideoPlayer, ConfiguredMediaPlayer, MediaPlayer, or when checking whether the installed package already exports a needed component.
+---
+
+# Use webs-sdk in a portal
+
+1. Read `references/components.md` to choose the existing component or library and its public import path. Read `references/integration.md` for the relevant usage and installation details.
+2. Verify the installed package version and exact public exports/types in `node_modules/webs-sdk/dist/index.d.ts` or `node_modules/webs-sdk/dist/components/ui/index.d.ts`. Catalog is a guide, not an exhaustive or version-independent API contract.
+3. Use `webs-sdk` or `webs-sdk/ui`; never import from private `dist/` paths. Keep default `WebsSDK` singleton out of client components. Add client boundary for interactive React UI. Consult installed `node_modules/webs-sdk/docs/` for feature-specific guidance.
+4. If functionality is absent, report the gap before creating shared functionality in a portal. Add reusable code to the SDK instead.

package/skills/webs-sdk-package/references/components.md

@@ -0,0 +1,30 @@
+# Component and capability map
+
+Choose an existing export before writing portal-specific code. Names below reflect the SDK source at packaging time; the installed package's `.d.ts` files are authoritative. Components accept different Props, API adapters and theme options: inspect their declarations rather than guessing required fields.
+
+## Root entry: `webs-sdk`
+
+| Goal | Exports to inspect | Where it fits |
+| --- | --- | --- |
+| Session, authentication, users, portal metadata | Default `WebsSDK` singleton: `Session`, `AuthManager`, `User`, `Andromeda`, `ContentManager`, `CorporateAuthManager`, `Legal`, `Networking`, `Storage`, `Config`, `.pre` | SDK orchestration, typically server-side in Next.js API routes/middleware. Do not directly bundle default singleton in client UI. |
+| Analytics and consent | `CookieConsent`, `getCookieConsentTexts`, `initGoogleAnalytics`, `updateGAConsent`, `trackGAEvent`, `trackGAPageView`, `isGALoaded`; singleton `MixPanel`, `Clarity`, `Calypso` | Cookie banner and opt-in GA; use consent APIs before loading analytics. |
+| CDN and media checks | `handleCDNRequest`, `validateVideoUrl`, `validateVideoBatch`, `useValidateVideoOnMount`, `useLazyVideoValidation` | CDN route handler, video URL validation and hooks; not a video player. |
+| Image/AI creation | `AvatarAI`, `CreativeFaceSwap`, `Wallpapers`, `WallpapersName`, `AETemplatesSection`, `MemeGenerator`, `Stickers`, `ARFilters`, `ArtGenerator`, `GifsIa`, `QrCode` | Standalone widgets and, where exported, `*Page` and `*ForYouCard` variants. Search Props for API/config/theme requirements. |
+| Other content | `Ringtone`, `Quiz`, `EsportsNews`, `EsportsVideos`, `EsportsLive` | Content widgets, quizzes, esports with API adapter/config types. |
+| For You page | `ForYouFullPage`, `ForYouPage`, `ForYouCard`, individual feature `*Card`, `useAvatarAI`, `useQuiz`, other `use*` hooks | Config-driven feature hub and reusable cards/hooks. Full page has config/theme/translation props; see installed `docs/FOR_YOU_IMPLEMENTATION_GUIDE.md`. |
+| Streak | `StreakWidget`, `StreakCard`, `StreakModal`, `StreakCelebration`, `useStreak` | Activity streak UI and data hook; see installed `docs/STREAK_IMPLEMENTATION_GUIDE.md`. |
+| Login support UI | `PasswordResetRequest`, `PasswordResetForm`, `RecoveryPassword` | Password recovery pieces; not a complete LoginPage. |
+| Forms | `ContactForm`, `ContactFormContent`, `createContactFormAPI` | Reusable configurable contact form. |
+| Networking/dev tools | `NetworkInspectorUI`, `trackRequest`, `trackResponse`, `getLogs`, `clearLogs`, `getStats` | Request inspection in development. |
+| Small utilities | `downloadFile`, `generateQRCode`, `getForYouTranslations`, `forYouFetch` | Reuse instead of copy/pasting helpers. |
+
+## UI entry: `webs-sdk/ui`
+
+| Goal | Export | Decision |
+| --- | --- | --- |
+| Prop-configured video/audio | `ConfiguredMediaPlayer` | Preferred new Radix player for a ready-to-use layout. Set `src`, optional `poster`, `tracks`, `sources`, `controls`; see `references/integration.md` and installed `docs/CONFIGURED_MEDIA_PLAYER.md`. |
+| Custom media controls | `MediaPlayer` plus `MediaPlayerVideo` / `MediaPlayerAudio`, `MediaPlayerControls`, `MediaPlayerPlay`, `MediaPlayerSeek`, `MediaPlayerTime`, `MediaPlayerVolume`, `MediaPlayerSettings`, `MediaPlayerFullscreen`, etc. | Composable Radix parts; root alone does not create media or controls. |
+| Existing/legacy video integration | `VideoPlayer` | Different API (`videoUrl`, `posterImage`, `languages`); retain for existing consumers. |
+| Standard UI primitives | `Button`, `Input`, `Dialog`, `DropdownMenu`, `Tabs`, `Select`, `Tooltip`, `Avatar`, `Accordion`, `Alert`, `Badge`, `Carousel`, `Checkbox`, `NavigationMenu`, `Textarea`, etc. | Use exported Radix primitives; inspect the installed `dist/components/ui/index.d.ts` for full list and types. |
+
+Both entry points have independent barrels. Import from `webs-sdk/ui` for UI, not `webs-sdk` or `webs-sdk/dist/...`. All React UI must run with a suitable client boundary and styling; consult `references/integration.md`.

package/skills/webs-sdk-package/references/integration.md

@@ -0,0 +1,32 @@
+# Install and use the SDK skill
+
+## Portal dependency and agent skill are separate
+
+1. Install the private npm package in the portal (requires registry access): `npm install webs-sdk`.
+2. To make the skill discoverable by Pi and other agents that support the Agent Skills directory convention, run from the portal root: `npm exec -- webs-sdk-skill`. This copies the skill to `.agents/skills/webs-sdk-package/`; commit that directory with the portal if teammates should get the skill. The installer never overwrites an existing installation unless called with `--force`. Restart the agent or reload skills. Installing npm package **alone does not activate** a skill in arbitrary agent tools.
+3. For Pi only, an alternative is `pi install npm:webs-sdk --local`: the package's `pi.skills` manifest enables its skill without copying files into the portal. This does **not** install `webs-sdk` as a dependency of the portal app: do step 1 as well. A personal install omits `--local`. Local Pi packages require project trust. Avoid enabling both paths simultaneously (duplicate skill names).
+4. Agent Skills-compatible tools can also load `skills/webs-sdk-package/SKILL.md` directly from the published package if configured to scan that directory. Other agents may require their own skill configuration.
+
+When upgrading the npm package, rerun `npm exec -- webs-sdk-skill --force` if you copied the skill. The published skill version tracks the npm package, but the installed app dependency, copied skill, and agent's running context can be out of sync. Always check the installed declarations at `node_modules/webs-sdk/dist/index.d.ts` and `node_modules/webs-sdk/dist/components/ui/index.d.ts` before coding.
+
+## Usage patterns
+
+```tsx
+'use client';
+import { ConfiguredMediaPlayer } from 'webs-sdk/ui';
+
+export function Video({ src }: { src: string }) {
+  return <ConfiguredMediaPlayer src={src} controls={{ seekButtons: true, pictureInPicture: true }} />;
+}
+```
+
+For Tailwind CSS v4, the portal CSS must explicitly scan the installed SDK UI directory (normally ignored under `node_modules`): add `@source "../../node_modules/webs-sdk/dist/components/ui";` relative to the CSS file. Adjust depth to the portal layout; without generated utilities UI controls may appear unstyled. Consult `node_modules/webs-sdk/docs/CONFIGURED_MEDIA_PLAYER.md` for props, HLS and captions. `ConfiguredMediaPlayer` and `MediaPlayer` are different from legacy `VideoPlayer`.
+
+```ts
+// In a server-side route/middleware, not a client component:
+import WebsSDK from 'webs-sdk';
+
+const metadata = await WebsSDK.Andromeda.getWebsiteMetadatabyHostname(hostname);
+```
+
+Do not assume a backend response shape, API keys, or portal theme. Inspect the relevant exported Props and feature guide; fetch backend data through the existing server-side pattern. `webs-sdk/ui` is a client-side React entry and does not initialize sessions, authentication or analytics for you.