@boldvideo/bold-js 0.7.0 → 0.8.0

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

@@ -1,215 +0,0 @@
----
-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