@boldvideo/bold-js 0.6.0 → 0.7.0

package/thoughts/shared/research/2025-10-22-BOLD-759-portal-color-scheme-settings.md

@@ -0,0 +1,215 @@
+---
+date: 2025-10-22T03:51:01+0000
+researcher: Claude Code
+git_commit: b74faa4e21936838e3aca23828c579b7d1da7a82
+branch: main
+repository: bold-js
+topic: "Adding portal.color_scheme to Settings Type in bold-js SDK"
+tags: [research, codebase, bold-js, settings, types, portal, BOLD-759]
+status: complete
+last_updated: 2025-10-22
+last_updated_by: Claude Code
+---
+
+# Research: Adding portal.color_scheme to Settings Type in bold-js SDK
+
+**Date**: 2025-10-22T03:51:01+0000
+**Researcher**: Claude Code
+**Git Commit**: b74faa4e21936838e3aca23828c579b7d1da7a82
+**Branch**: main
+**Repository**: bold-js
+**Linear Ticket**: [BOLD-759](https://linear.app/boldvideo/issue/BOLD-759/add-portalcolor-scheme-to-settings-type-in-bold-js-sdk)
+
+## Research Question
+
+Where and how should the `color_scheme` field be added to the Settings type in the bold-js SDK to support the Next.js starter's theme configuration?
+
+## Summary
+
+The `color_scheme` field needs to be added to the `Portal` type definition in `/Users/marcelfahle/code/BOLD/code/_oss/bold-js/src/lib/types.ts` at line 133. The Portal type is already part of the Settings type (line 210), so adding the field to Portal will automatically make it available in Settings. The SDK already has established patterns for optional fields and will automatically export the updated type through the main index file.
+
+## Detailed Findings
+
+### Current Settings Type Structure
+
+The Settings type is defined in `src/lib/types.ts:179-217` with the following key components:
+
+**Portal Object Location**: `src/lib/types.ts:210`
+```typescript
+portal: Portal
+```
+
+The Portal type itself is defined at `src/lib/types.ts:133-138`:
+```typescript
+export type Portal = {
+  display: PortalDisplay;
+  layout: PortalLayout;
+  navigation: PortalNavigation;
+  theme: PortalTheme;
+};
+```
+
+### Where to Add color_scheme
+
+The `color_scheme` field should be added directly to the `Portal` type definition at `src/lib/types.ts:133-138`. Based on the ticket requirements, it should be:
+
+**Type**: `'toggle' | 'light' | 'dark'`
+**Optional**: Yes (using the `?` suffix)
+**Location**: Portal type definition
+
+The field would be added as a new property alongside the existing nested objects (display, layout, navigation, theme).
+
+### Existing Portal Structure
+
+The Portal type currently contains four nested configuration objects:
+
+1. **display: PortalDisplay** (`src/lib/types.ts:98-101`)
+   - `show_chapters: boolean`
+   - `show_transcripts: boolean`
+
+2. **layout: PortalLayout** (`src/lib/types.ts:109-114`)
+   - `assistant_config: AssistantConfig | null`
+   - `show_playlists: boolean`
+   - `type: string`
+   - `videos_limit: number`
+
+3. **navigation: PortalNavigation** (`src/lib/types.ts:116-120`)
+   - `show_ai_search: boolean`
+   - `show_header: boolean`
+   - `show_search: boolean`
+
+4. **theme: PortalTheme** (`src/lib/types.ts:122-131`)
+   - `background: string`
+   - `font_body: string`
+   - `font_header: string`
+   - `foreground: string`
+   - `logo_height: number`
+   - `logo_url: string`
+   - `logo_width: number`
+   - `primary: string`
+
+### Optional Field Pattern in Settings
+
+The SDK has a consistent pattern for optional fields using the TypeScript `?:` syntax:
+
+**Examples from Settings type** (`src/lib/types.ts:179-217`):
+- `ai_greeting?: string` (line 187)
+- `favicon_url?: string` (line 194)
+- `logo_dark_url?: string` (line 195)
+- `logo_url?: string` (line 196)
+- `social_graph_image_url?: string` (line 204, nested in meta_data)
+
+**Examples from Video type** (`src/lib/types.ts:33-80`):
+- `chapters?: string`
+- `attachments?: VideoAttachment[]`
+- `internal_id?: string`
+- `playback_speed?: number`
+- `tags?: string[]`
+- `transcript?: VideoTranscript`
+
+### Union Type Pattern
+
+Currently, the Settings type and its nested types don't extensively use string literal union types. The closest patterns are:
+
+**Null unions**:
+- `assistant_config: AssistantConfig | null` (`src/lib/types.ts:110`)
+- `image: string | null` (`src/lib/types.ts:202`)
+
+The proposed `'toggle' | 'light' | 'dark'` union type would be a new pattern for the Settings type, though it's a standard TypeScript pattern.
+
+### Type Export Chain
+
+The Portal type follows this export chain:
+
+1. **Definition**: `src/lib/types.ts:133-138` - Portal type is exported
+2. **Re-export**: `src/index.ts:12` - Portal is re-exported from main entry
+3. **Compilation**: `dist/index.d.ts` - Type declarations are generated by tsup
+4. **Consumption**: Available to consumers via `import type { Portal } from '@boldvideo/bold-js'`
+
+Any changes to the Portal type will automatically flow through this chain when the project is rebuilt.
+
+### Settings API Usage
+
+The Settings type is fetched via the `fetchSettings` function in `src/lib/fetchers.ts:26-38`:
+
+```typescript
+export function fetchSettings(client: ApiClient) {
+  return async (videoLimit = 12) => {
+    try {
+      return await get<Response<Settings>>(
+        client,
+        `settings?limit=${videoLimit}`
+      );
+    } catch (error) {
+      console.error(`Error fetching settings with limit: ${videoLimit}`, error);
+      throw error;
+    }
+  };
+}
+```
+
+The function returns a `Response<Settings>` wrapper type where Settings includes the portal object. The API endpoint is `settings?limit=${videoLimit}`.
+
+## Code References
+
+- `src/lib/types.ts:133-138` - Portal type definition (where color_scheme should be added)
+- `src/lib/types.ts:179-217` - Settings type definition
+- `src/lib/types.ts:210` - Portal field in Settings type
+- `src/index.ts:12` - Portal type re-export
+- `src/lib/fetchers.ts:26-38` - fetchSettings API implementation
+
+## Architecture Documentation
+
+### Type Definition Pattern
+
+The SDK uses a modular type system where:
+
+1. Small, focused types are defined for specific concepts (PortalDisplay, PortalLayout, etc.)
+2. These types are composed into larger structures (Portal contains display, layout, navigation, theme)
+3. The Settings type brings everything together at the top level
+4. All types are exported individually, allowing consumers to use them independently
+
+### Build and Type Generation
+
+- **Build tool**: tsup
+- **Source**: TypeScript files in `src/`
+- **Output**: ESM and CommonJS in `dist/` with type declarations
+- **Type declarations**: Generated automatically in `dist/index.d.ts`
+
+### Backward Compatibility
+
+The Settings type maintains backward compatibility by:
+
+- Keeping legacy flat AI fields (`ai_avatar`, `ai_name`, `has_ai`) while adding new nested `account` structure
+- Using optional fields for new additions to prevent breaking changes
+- Defaulting to sensible values (as specified in the ticket: default to "toggle" if not specified)
+
+## Related Research
+
+This research is specific to BOLD-759. No previous research documents were found in the thoughts directory related to Settings type modifications.
+
+## Implementation Context
+
+According to the Linear ticket:
+
+**Purpose**: The Next.js starter now reads `portal.color_scheme` from the settings API to control theme behavior, but this field is not yet defined in the bold-js SDK Settings type.
+
+**Expected behavior**:
+- `"toggle"`: Show theme toggle, allow user to switch between light/dark
+- `"light"`: Force light mode, hide theme toggle
+- `"dark"`: Force dark mode, hide theme toggle
+- Default to `"toggle"` if not specified
+
+**Already implemented**: The implementation is live in production in these commits:
+- main: b31396f
+- demo/founderwell: b42c9fe
+- custom/yo: b9d8ee8
+
+The API is already returning this field; the SDK types just need to be updated to reflect it.
+
+## Notes
+
+- No string literal union types currently exist in the Settings/Portal types, so this would introduce that pattern
+- The field should be optional to maintain backward compatibility
+- The type will automatically be available to consumers after the SDK is rebuilt and published
+- No changes needed to the API fetcher code - it already returns the full Settings object

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "restricted",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.github/dependabot.yml

@@ -1,11 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "npm"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    open-pull-requests-limit: 10
-    groups:
-      dependencies:
-        patterns:
-          - "*"

package/.github/workflow/main.yml

@@ -1,21 +0,0 @@
-name: CI
-on:
-  push:
-    branches:
-      - "**"
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: pnpm/action-setup@v2
-        with:
-          version: 7
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 16.x
-          cache: "pnpm"
-
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm run lint && pnpm run build

package/.github/workflow/publish.yml

@@ -1,29 +0,0 @@
-name: Publish
-on:
-  push:
-    branches:
-      - "main"
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: pnpm/action-setup@v2
-        with:
-          version: 7
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 16.x
-          cache: "pnpm"
-
-      - run: pnpm install --frozen-lockfile
-      - name: Create Release Pull Request or Publish
-        id: changesets
-        uses: changesets/action@v1
-        with:
-          publish: pnpm run build
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/changeset-release.yml

@@ -1,51 +0,0 @@
-name: Changeset Release
-
-on:
-  push:
-    branches:
-      - main
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-permissions:
-  contents: write
-  pull-requests: write
-  id-token: write  # For npm provenance
-
-jobs:
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v2
-        with:
-          version: 10.12.2
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20.x
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
-      
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-      
-      - name: Create Release Pull Request or Publish to npm
-        id: changesets
-        uses: changesets/action@v1
-        with:
-          title: "chore: release package"
-          commit: "chore: release package"
-          publish: pnpm changeset publish
-          createGithubReleases: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NPM_CONFIG_PROVENANCE: true

package/.github/workflows/ci.yml

@@ -1,90 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  test:
-    name: Test on Node ${{ matrix.node-version }}
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [20.x, 22.x, 24.x]
-    
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v2
-        with:
-          version: 10.12.2
-      
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'pnpm'
-      
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-      
-      - name: Run linter
-        run: pnpm run lint
-      
-      - name: Build package
-        run: pnpm run build
-      
-      - name: Check package exports
-        run: |
-          node -e "const pkg = require('./dist/index.cjs'); console.log('CJS import successful');"
-          node -e "import('./dist/index.js').then(() => console.log('ESM import successful'));"
-      
-      - name: Check TypeScript declarations
-        run: |
-          if [ ! -f "dist/index.d.ts" ]; then
-            echo "TypeScript declarations not found!"
-            exit 1
-          fi
-
-  size-check:
-    name: Bundle Size Check
-    runs-on: ubuntu-latest
-    
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v2
-        with:
-          version: 10.12.2
-      
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.x
-          cache: 'pnpm'
-      
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-      
-      - name: Build package
-        run: pnpm run build
-      
-      - name: Check bundle size
-        run: |
-          echo "Bundle sizes:"
-          ls -lh dist/
-
-          # Warn if bundle exceeds 50KB (adjust threshold as needed)
-          size=$(node -e "console.log(require('fs').statSync('dist/index.js').size)")
-          if [ $size -gt 51200 ]; then
-            echo "⚠️  Warning: Bundle size exceeds 50KB (current: ${size} bytes)"
-          else
-            echo "✅ Bundle size OK: ${size} bytes"
-          fi

package/.github/workflows/release.yml

@@ -1,83 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-permissions:
-  contents: read
-  id-token: write  # For npm provenance
-
-jobs:
-  release:
-    name: Release to npm
-    runs-on: ubuntu-latest
-    
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Needed for changelog generation
-      
-      - name: Install pnpm
-        uses: pnpm/action-setup@v2
-        with:
-          version: 10.12.2
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20.x
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
-      
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-      
-      - name: Run CI checks
-        run: |
-          pnpm run lint
-          pnpm run build
-      
-      - name: Verify version matches tag
-        run: |
-          PACKAGE_VERSION="v$(node -p "require('./package.json').version")"
-          if [ "$PACKAGE_VERSION" != "${{ github.ref_name }}" ]; then
-            echo "Error: Package version ($PACKAGE_VERSION) doesn't match tag (${{ github.ref_name }})"
-            exit 1
-          fi
-      
-      - name: Check npm access
-        run: npm whoami
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      
-      - name: Publish to npm with provenance
-        run: pnpm publish --access public --no-git-checks
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NPM_CONFIG_PROVENANCE: true
-      
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v1
-        with:
-          generate_release_notes: true
-          body: |
-            ## What's Changed
-            
-            See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details.
-            
-            ## Installation
-            
-            ```bash
-            npm install @boldvideo/bold-js@${{ github.ref_name }}
-            ```
-            
-            ```bash
-            pnpm add @boldvideo/bold-js@${{ github.ref_name }}
-            ```
-            
-            ```bash
-            yarn add @boldvideo/bold-js@${{ github.ref_name }}
-            ```

package/CLAUDE.md

@@ -1,76 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is the Bold JavaScript SDK (`@boldvideo/bold-js`) - a TypeScript client library for interacting with the Bold Video API. The SDK provides methods for fetching videos, playlists, channel settings, and tracking analytics events.
-
-## Common Development Commands
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build the project (outputs to dist/)
-pnpm run build
-
-# Run type checking/linting
-pnpm run lint
-
-# Publish new version (uses changesets)
-pnpm changeset
-pnpm changeset version
-pnpm changeset publish
-```
-
-## Architecture & Key Components
-
-### Client Structure
-The SDK uses a factory pattern where `createClient(apiKey)` returns an object with namespaced methods:
-- `bold.settings()` - Fetch channel settings
-- `bold.videos.list()` / `.get(id)` / `.search(query)` - Video operations
-- `bold.playlists.list()` / `.get(id)` - Playlist operations
-- `bold.trackEvent()` / `bold.trackPageView()` - Analytics tracking
-
-### Core Files
-- `/src/index.ts` - Main entry point, exports `createClient` and all types
-- `/src/lib/client.ts` - Client factory that creates the Bold instance with API key auth
-- `/src/lib/fetchers.ts` - Individual API endpoint implementations
-- `/src/lib/tracking.ts` - Analytics event tracking with throttling
-- `/src/lib/types.ts` - TypeScript interfaces for Video, Playlist, Settings, etc.
-- `/src/util/throttle.ts` - Throttling utility for rate-limiting event tracking
-
-### Build Configuration
-- Uses `tsup` for building TypeScript to both ESM and CommonJS formats
-- Outputs to `/dist/` with type declarations
-- TypeScript strict mode enabled
-- Target: ES2016
-
-## Development Workflow
-
-1. The project uses GitHub Actions for CI/CD:
-   - All branches run lint and build checks
-   - Main branch can publish to npm using changesets
-
-2. When making changes:
-   - Ensure TypeScript types are properly defined
-   - Run `pnpm run lint` before committing
-   - The SDK supports both ESM and CommonJS consumers
-
-3. API Integration:
-   - Default base URL: `https://app.boldvideo.io/api/v1/`
-   - Authentication via API key in Authorization header
-   - All API methods return promises
-
-4. Analytics Tracking:
-   - Events are throttled to prevent API rate limiting
-   - User IDs are auto-generated for each client instance
-   - Debug mode available for development
-
-## Important Notes
-
-- No test framework is currently configured
-- The SDK is designed to be lightweight with minimal dependencies (only axios)
-- All API responses follow the type definitions in `/src/lib/types.ts`
-- The tracking system includes automatic throttling to handle high-frequency events like video progress updates