@boldvideo/bold-js 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @boldvideo/bold-js
 
+## 0.7.1
+
+### Patch Changes
+
+- Fix: Add thoughts directory to .npmignore to prevent publishing internal planning files
+
 ## 0.7.0
 
 ### Minor Changes

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boldvideo/bold-js",
   "license": "MIT",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -1,272 +0,0 @@
-# Add portal.color_scheme to Settings Type Implementation Plan
-
-## Overview
-
-Add the `color_scheme` field to the `Portal` type in the bold-js SDK to support the Next.js starter's theme configuration feature. The API already returns this field in production; we need to update the TypeScript types to reflect this.
-
-## Current State Analysis
-
-**What exists:**
-- Portal type defined at `src/lib/types.ts:133-138` with four nested objects (display, layout, navigation, theme)
-- Portal type properly exported through `src/index.ts:12`
-- Settings type at `src/lib/types.ts:210` includes the Portal object
-- API already returning `portal.color_scheme` field (live in production)
-- Next.js starter consuming this field but TypeScript doesn't know about it
-
-**What's missing:**
-- `color_scheme` field in the Portal type definition
-- Type definition doesn't match the API response
-- Consumers can't benefit from TypeScript autocomplete/validation for this field
-
-**Key constraints:**
-- Must maintain backward compatibility (field should be optional)
-- Must follow existing optional field pattern (using `?` suffix)
-- This will be the first string literal union type in Portal/Settings types
-- Project uses changesets for version management
-- No existing test suite to update
-
-## Desired End State
-
-After implementation:
-1. Portal type includes `color_scheme?: 'toggle' | 'light' | 'dark'` field
-2. TypeScript consumers get autocomplete for the three valid values
-3. Type declarations are rebuilt and available in `dist/index.d.ts`
-4. Version bumped to 0.7.0 with appropriate changelog entry
-5. Changes published to npm
-
-**Verification:**
-- Portal type includes the new field with correct union type
-- Build succeeds without errors: `pnpm run build`
-- Type checking passes: `pnpm run lint`
-- Compiled type declarations in `dist/index.d.ts` include the field
-- Changeset created for version 0.7.0
-
-## What We're NOT Doing
-
-- Not adding runtime validation for the color_scheme values
-- Not adding tests (no test framework exists in this project)
-- Not modifying the API or fetcher functions (they already work correctly)
-- Not changing any other types or fields
-- Not adding documentation beyond the changelog entry
-- Not updating example code or README (out of scope for this ticket)
-
-## Implementation Approach
-
-This is a single-phase implementation because:
-1. It's a one-line type change
-2. No runtime code changes required
-3. No migration needed (field is optional)
-4. Build and publish can happen together
-
-The approach:
-1. Add the `color_scheme` field to Portal type
-2. Create changeset for version bump
-3. Build to verify TypeScript compilation
-4. Commit changes following git conventions
-
-## Phase 1: Add color_scheme Field
-
-### Overview
-
-Add the `color_scheme` field to the Portal type definition following the SDK's established patterns for optional fields.
-
-### Changes Required
-
-#### 1. Update Portal Type Definition
-
-**File**: `src/lib/types.ts`
-**Line**: 133-138
-**Changes**: Add `color_scheme` as the first field in the Portal type
-
-```typescript
-export type Portal = {
-  color_scheme?: 'toggle' | 'light' | 'dark';
-  display: PortalDisplay;
-  layout: PortalLayout;
-  navigation: PortalNavigation;
-  theme: PortalTheme;
-};
-```
-
-**Rationale:**
-- Optional field (`?`) maintains backward compatibility
-- String literal union type provides type safety and autocomplete
-- Positioned first in the type as it's a top-level configuration (similar to how top-level fields appear before nested objects in Settings)
-- Follows TypeScript best practices for union types
-
-#### 2. Create Changeset
-
-**Command**: `pnpm changeset`
-
-**Changeset content:**
-```markdown
----
-"@boldvideo/bold-js": minor
----
-
-Add `color_scheme` field to Portal type (BOLD-759)
-
-Added optional `color_scheme` field to the Portal type to support theme configuration:
-- `'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
-
-This field is already returned by the API and consumed by the Next.js starter. The type definition now matches the API response.
-```
-
-**Why minor version:**
-- Adds new functionality (new field) to the public API
-- Follows semantic versioning: backward compatible API addition
-- Matches pattern from CHANGELOG.md (v0.5.0 added `ai_greeting`, v0.6.0 added portal object)
-
-### Success Criteria
-
-#### Automated Verification:
-
-- [x] Portal type includes `color_scheme?: 'toggle' | 'light' | 'dark'` field in correct position
-- [x] Build completes successfully: `pnpm run build`
-- [x] Type checking passes: `pnpm run lint` (runs `tsc`)
-- [x] Compiled declarations in `dist/index.d.ts` include the new field
-- [x] Git status shows only expected changes: `src/lib/types.ts` and changeset file
-
-#### Manual Verification:
-
-- [x] Type change makes semantic sense (three valid theme modes)
-- [x] Field placement is logical within the Portal type structure
-- [x] Changeset message accurately describes the change
-- [x] No unintended changes to other types
-
-## Phase 2: Version and Publish
-
-### Overview
-
-Use changesets to version the package and publish to npm.
-
-### Changes Required
-
-#### 1. Version the Package
-
-**Command**: `pnpm changeset version`
-
-**Expected changes:**
-- `package.json` version bumped from `0.6.1` to `0.7.0`
-- `CHANGELOG.md` updated with changeset content under `## 0.7.0`
-- Changeset file consumed and removed
-
-#### 2. Build for Distribution
-
-**Command**: `pnpm run build`
-
-**Expected output:**
-- `dist/index.js` (ESM)
-- `dist/index.cjs` (CommonJS)
-- `dist/index.d.ts` (TypeScript declarations)
-
-The build must succeed and include the new `color_scheme` field in type declarations.
-
-#### 3. Publish to npm
-
-**Command**: `pnpm changeset publish`
-
-**Expected behavior:**
-- Package tagged as `v0.7.0`
-- Published to npm registry with public access
-- Git tag created for the release
-
-### Success Criteria
-
-#### Automated Verification:
-
-- [x] `package.json` shows version `0.7.0`
-- [x] `CHANGELOG.md` includes entry for version `0.7.0` with BOLD-759 reference
-- [x] Build completes without errors: `pnpm run build`
-- [x] Type declarations in `dist/index.d.ts` include `color_scheme` field
-- [ ] Package published successfully to npm (requires manual 2FA)
-- [ ] Git tag `v0.7.0` created (created by publish command)
-
-#### Manual Verification:
-
-- [ ] Published package on npm shows correct version (pending publish)
-- [ ] Type declarations are available to consumers (pending publish)
-- [x] CHANGELOG.md entry is accurate and well-formatted
-- [x] All files committed with appropriate git message (following project conventions)
-
-## Testing Strategy
-
-### Unit Tests
-
-Not applicable - this project has no test suite.
-
-### Integration Tests
-
-Not applicable - no test framework configured.
-
-### Manual Testing Steps
-
-Since this is a type-only change, manual testing focuses on verification that TypeScript types work correctly:
-
-1. **Verify type compilation:**
-   ```bash
-   pnpm run lint  # Runs tsc to check types
-   ```
-
-2. **Verify build output:**
-   ```bash
-   pnpm run build
-   # Check that dist/index.d.ts contains the new field
-   cat dist/index.d.ts | grep -A 5 "type Portal"
-   ```
-
-3. **Verify in a consumer project (optional):**
-   - Link the package locally: `pnpm link @boldvideo/bold-js`
-   - In a TypeScript project, import and use the type:
-     ```typescript
-     import { createClient } from '@boldvideo/bold-js';
-
-     const bold = createClient('api-key');
-     const settings = await bold.settings();
-
-     // TypeScript should autocomplete 'toggle' | 'light' | 'dark'
-     const colorScheme = settings.data.portal.color_scheme;
-     ```
-
-## Performance Considerations
-
-None - this is a compile-time only change. No runtime performance impact.
-
-## Migration Notes
-
-No migration required. The field is optional and backward compatible:
-
-**For existing consumers:**
-- Upgrading to 0.7.0 requires no code changes
-- The `color_scheme` field will be `undefined` if not returned by the API
-- Type checking will help consumers handle the field correctly if they choose to use it
-
-**API compatibility:**
-- API already returns this field (in production since commits b31396f, b42c9fe, b9d8ee8)
-- Older SDK versions will ignore the field (no breaking changes)
-- Newer SDK versions provide type safety for the field
-
-## References
-
-- Original ticket: [BOLD-759](https://linear.app/boldvideo/issue/BOLD-759/add-portalcolor-scheme-to-settings-type-in-bold-js-sdk)
-- Research document: `thoughts/shared/research/2025-10-22-BOLD-759-portal-color-scheme-settings.md`
-- Portal type definition: `src/lib/types.ts:133-138`
-- Settings type definition: `src/lib/types.ts:179-217`
-- Type exports: `src/index.ts:12`
-
-## Implementation Notes
-
-**Field positioning rationale:**
-The `color_scheme` field should be placed first in the Portal type because:
-1. It's a direct configuration value (not a nested object like display/layout/navigation/theme)
-2. Follows the pattern in Settings type where direct values come before nested objects
-3. Makes the type more readable - simple values first, complex nested types after
-
-**Union type introduction:**
-This is the first string literal union type in Portal/Settings types. While the existing types use simple primitives (`string`, `boolean`, `number`), using a union type here provides:
-1. Type safety - prevents invalid values
-2. Better developer experience - autocomplete in IDEs
-3. Self-documenting code - valid values are in the type definition
-4. Follows TypeScript best practices for known string values

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