webs-sdk 0.19.64 → 0.19.66

package/AGENTS.md

@@ -0,0 +1,44 @@
+# Agent guide: webs-sdk
+
+`webs-sdk` is a shared package for Nexum portals. Prefer an existing SDK export over copying a component or implementing shared behavior in a portal. This guide ships with the npm package. For automatic skill discovery in a consuming portal, run `npm exec -- webs-sdk-skill` after `npm install webs-sdk`; restart the agent. Pi can instead load the packaged skill with `pi install npm:webs-sdk --local` (requires a separate `npm install webs-sdk` for the portal). Without the skill, agents must explicitly read `node_modules/webs-sdk/AGENTS.md` because nested `node_modules` instructions are not automatically loaded. See `skills/webs-sdk-package/references/components.md` for the component map. Inspect `node_modules/webs-sdk/dist/index.d.ts` and `node_modules/webs-sdk/dist/components/ui/index.d.ts` for the **installed version's** exact exports and Props types; guides are not exhaustive. In the SDK source repository, read `CLAUDE.md` before editing code.
+
+## Choose the correct import
+
+| Need | Import | Details |
+| --- | --- | --- |
+| Session, authentication, API, tracking, CDN, feature components | `webs-sdk` | Root public API in `src/index.ts`. Server/client suitability varies by export; do not put the whole `WebsSDK` singleton in a client component without checking its dependencies. |
+| Radix primitives and media players | `webs-sdk/ui` | UI public API in `src/components/ui/index.ts`. Use this subpath, not private `dist/` paths. |
+| Video with source, captions, controls configured via props | `ConfiguredMediaPlayer` from `webs-sdk/ui` | See `docs/CONFIGURED_MEDIA_PLAYER.md`. This is the preferred ready-to-use Radix player. |
+| Custom video/audio control layout | `MediaPlayer` and `MediaPlayer*` from `webs-sdk/ui` | Compose children under `MediaPlayer`; no default media/controls are created for you. |
+| Existing portals using the old video player | `VideoPlayer` from `webs-sdk/ui` | Legacy API (`videoUrl`, `posterImage`, `languages`). Do not silently replace with the new player: props and rendering differ. |
+
+## Portal integration: prop-configured video
+
+```tsx
+'use client';
+
+import { ConfiguredMediaPlayer } from 'webs-sdk/ui';
+
+export function ContentVideo({ url, poster }: { url: string; poster?: string }) {
+  return (
+    <ConfiguredMediaPlayer
+      src={url}
+      poster={poster}
+      label="Content video"
+      controls={{ seekButtons: true, captions: true, pictureInPicture: true }}
+      tracks={[{ src: '/subtitles/en.vtt', srcLang: 'en', label: 'English', kind: 'subtitles' }]}
+    />
+  );
+}
+```
+
+`src` is required, not `videoUrl`. `controls` overrides individual defaults; `settings` defaults to enabled, so use `{ settings: false, speed: true }` to show the standalone speed picker. HLS `.m3u8` loads natively where supported, otherwise loads `hls.js` on demand. Consumers need React/ReactDOM and the declared `lucide-react` peer dependency. Configure the portal's Tailwind v4 scan to include SDK UI files (`@source` path in `docs/CONFIGURED_MEDIA_PLAYER.md`); otherwise player controls may render without styling. Media playback requires a client component; merely importing an SDK component does not replace the portal's auth/session logic.
+
+## Before adding a reusable feature
+
+1. In a consuming portal, check the installed `webs-sdk` version and its `dist/index.d.ts` / `dist/components/ui/index.d.ts`, then inspect the exported Props declarations. Do not import from private `dist/` paths in application code.
+2. Prefer an existing SDK export in a portal. If no reusable feature exists, add it to the SDK source repository rather than copying implementations into multiple portals.
+3. When editing the SDK repository, check `src/index.ts` and `src/components/ui/index.ts`, use relative imports, export public Props/Config types, and add focused tests. Root exports require both `src/index.ts` and root `index.js`; `webs-sdk/ui` exports require `src/components/ui/index.ts` only.
+4. In the SDK repository, run `npm test`, `npm run test:types`, `npm run test:package`, and `npm run test:coverage` before release. Package checks verify `webs-sdk` and `webs-sdk/ui` entry points. Do not edit `dist/` by hand or bump the version manually.
+
+Other guides: `CLAUDE.md` (development and publishing), `README.md` (public SDK overview), `docs/CONFIGURED_MEDIA_PLAYER.md` (media API), `docs/FOR_YOU_IMPLEMENTATION_GUIDE.md` and `docs/STREAK_IMPLEMENTATION_GUIDE.md` (feature integration).

package/CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+## What this repo is
+
+`webs-sdk` — internal npm package for Nexum web portals. Provides shared libraries (auth, sessions, networking, tracking, i18n, storage) and reusable React components (AvatarAI, Wallpapers, SpinningWheel, ARFilters, etc.). Published artifact is `dist/` (CommonJS, ES2017), plus `AGENTS.md`, `CLAUDE.md`, and `docs/` for agents working in consuming portals. The Next.js setup (`npm run dev`) is dev-only for visually testing components. For a portal integration decision tree and ready-to-copy media player example, start with `AGENTS.md`.
+
+## Commands
+
+```bash
+npm run build          # Compile src/ → dist/ via tsc (tsconfig.build.json)
+npm run build:watch    # Same, with --watch
+npm run dev            # Next.js dev server (component testing only)
+npm run lint           # ESLint (Next.js 16 flat config; existing source lint debt remains)
+npm test               # Vitest unit and browser-component tests (single run)
+npm run test:watch     # Vitest watch mode
+npm run test:coverage  # V8 coverage across all src/ files, including untouched files
+npm run test:types     # Typecheck SDK and test files without migration scratch files
+npm run test:package   # Build and verify published SDK/UI entry points and root exports
+```
+
+Run `npm test`, `npm run test:types`, `npm run test:package`, and `npm run test:coverage` locally when changing SDK code. These tests do not call live backends. Test tooling needs Node.js 20.19+ (or 22.12+). Tests live in `tests/`; the build excludes them. Browser tests use `// @vitest-environment jsdom`. Coverage includes untested `src/` files at 0%; passing tests do not imply full SDK coverage. Full `npm run lint` currently reports pre-existing source errors; do not suppress them.
+
+## Architecture essentials
+
+```
+src/
+├── index.ts              # Source barrel — all public exports
+├── config.ts             # Static defaults, mutated at runtime by executeInit()
+├── libraries/            # Core services (classes, instantiated as singletons)
+│   ├── networking.ts     # HTTP, events, /config init
+│   ├── session.ts        # Session orchestration (init flow entry point)
+│   ├── auth.ts           # JWT auth
+│   ├── andromeda.ts      # AI backend client
+│   ├── calypso.ts        # AI backend client (alt)
+│   ├── mixpanel.ts       # Mixpanel tracking
+│   ├── storage.ts        # localStorage wrapper
+│   └── ...
+├── components/           # React components (self-contained, export types)
+│   ├── AvatarAI.tsx      # Single-file components with inline CSS
+│   ├── SpinningWheel/    # Multi-file components in folders
+│   └── ui/               # Shared UI primitives (radix-based)
+└── utils/                # Pure utility functions
+```
+
+**Public entry points (see `package.json`):**
+- `webs-sdk` — `src/index.ts` is the TypeScript source barrel; root `/index.js` is the manually maintained CJS re-export. When adding a **root** export, update BOTH.
+- `webs-sdk/ui` — `src/components/ui/index.ts` is its own barrel. When adding a **UI-only** export, update this barrel; no root export or root `/index.js` change is needed. Do not import from private `dist/` paths.
+
+**Media player choice:** `ConfiguredMediaPlayer` accepts `src`, `poster`, `tracks`, `sources`, `controls`, and playback callbacks as props; use it for a ready-to-use Radix video/audio player. `MediaPlayer` plus `MediaPlayer*` parts is for custom control layouts. Existing `VideoPlayer` has a different API (`videoUrl`, `posterImage`, `languages`) and remains for backward compatibility. All three are in `webs-sdk/ui`. See `docs/CONFIGURED_MEDIA_PLAYER.md` for usage and Tailwind v4 `@source` integration; see `tests/mediaPlayer.test.tsx` for tests.
+
+**Singleton SDK object** (`src/index.ts`): `WebsSDK` instantiates all libraries as singletons. A lazy `.pre` namespace provides preproduction instances (different backend URL).
+
+**Init flow** (`Session.init()`):
+1. `storeSessionStructure()` — browser/device info
+2. `checkUserID()` — fetch or create user ID
+3. `networking.executeInit()` — fetches `/config`, mutates `config.ts` with endpoints, events, paywall data, image compression settings
+4. `checkFirstOpen()` — sends `first_open` event
+
+## Conventions
+
+- **Language**: Code in English, comments often in Spanish
+- **Components**: Most feature components are self-contained with inline CSS strings and export Props/Config/Theme/Texts types. UI primitives and Radix media players in `src/components/ui/` use Tailwind classes; consuming portals must scan the installed SDK UI files. See `docs/CONFIGURED_MEDIA_PLAYER.md`.
+- **Libraries**: Class-based, each file exports a class and a default instance
+- **Environment handling**: Constructor param `'production' | 'preproduction'` switches `backendBaseUrl`
+- **Path aliases**: `@/*` → `./src/*` works in Next.js dev but NOT in the library build (`tsconfig.build.json` uses `moduleResolution: "node"`). Use relative imports in `src/`.
+- **Tests** — add unit tests in `tests/` for new behavior, then run `npm test` and `npm run build`
+- **Do not bump `package.json` version** manually
+
+## Publishing / CI
+
+- `prepublishOnly` still runs only `npm run build`; local tests are not a publication gate
+- Version bumping and publishing are handled by CI when commit messages contain a ticket reference `[ROAD-XXXXXX]`
+- `builder.config.json` is for the visual Builder.io integration (dev only)
+
+## Gotchas
+
+- `config.ts` exports a mutable object — `Networking.executeInit()` overwrites endpoint URLs, events, and feature flags at runtime
+- The build uses `jsx: "react-jsx"` (see `tsconfig.build.json`)
+- `tsconfig.build.json` extends `tsconfig.json` but overrides key settings (CommonJS, no emit in base, emit in build)
+- `skipLibCheck: true` in build config — type errors in `node_modules` won't surface