hazo_config 1.4.2 → 2.0.2

package/MIGRATION_V2.md

@@ -0,0 +1,531 @@
+# Migration Guide: hazo_config v1 → v2
+
+## Breaking Changes Summary
+
+Version 2.0.0 introduces a major schema change to support JSON configuration values and replace `org_id` with `scope_id`. This is a **BREAKING CHANGE** requiring code updates and database migration.
+
+## What Changed
+
+### 1. Database Schema
+
+**Old Schema:**
+```sql
+CREATE TABLE hazo_app_config (
+  id TEXT PRIMARY KEY,
+  org_id TEXT,
+  user_id TEXT,
+  config_section TEXT NOT NULL,
+  config_name TEXT NOT NULL,
+  config_value TEXT NOT NULL,
+  created_at TEXT,
+  changed_at TEXT
+)
+```
+
+**New Schema:**
+```sql
+CREATE TABLE hazo_app_config (
+  id TEXT PRIMARY KEY,
+  scope_id TEXT,                           -- ← CHANGED: org_id → scope_id
+  user_id TEXT,
+  config_section TEXT NOT NULL,
+  config_name TEXT NOT NULL,
+  config_value_text TEXT,                  -- ← NEW: for general type
+  config_value_json TEXT,                  -- ← NEW: for json type (JSONB in PostgreSQL)
+  config_type TEXT NOT NULL,               -- ← NEW: 'general' or 'json'
+  created_at TEXT,
+  changed_at TEXT,
+  CHECK (
+    (config_type = 'general' AND config_value_text IS NOT NULL AND config_value_json IS NULL) OR
+    (config_type = 'json' AND config_value_json IS NOT NULL AND config_value_text IS NULL)
+  )
+)
+```
+
+### 2. Type Definitions
+
+**Removed:**
+- `ConfigLevel` type ('org' | 'user')
+
+**Added:**
+- `ConfigType` type ('json' | 'general')
+
+**Changed Interface:**
+```typescript
+// OLD
+interface AppConfigItem {
+  org_id: string | null
+  config_value: string
+}
+
+// NEW
+interface AppConfigItem {
+  scope_id: string | null        // ← org_id renamed
+  config_value_text: string      // ← new field
+  config_value_json: object      // ← new field
+  config_type: ConfigType        // ← new field
+}
+
+// OLD
+interface AppConfigContext {
+  org_id: string
+  user_id?: string
+}
+
+// NEW
+interface AppConfigContext {
+  scope_id: string              // ← org_id renamed
+  user_id?: string
+}
+```
+
+### 3. Component API Changes
+
+**AppConfig Component:**
+```typescript
+// OLD
+<AppConfig
+  level="org"              // ← REMOVED
+  context={{ org_id: '...' }}
+  fetch_config={fetch_config}
+  save_config={save_config}
+  delete_config={delete_config}
+/>
+
+// NEW
+<AppConfig
+  title="Scope Settings"    // ← Now required (no default from level)
+  context={{ scope_id: '...' }}
+  fetch_config={fetch_config}
+  save_config={save_config}
+  delete_config={delete_config}
+/>
+```
+
+**Hook Signature:**
+```typescript
+// OLD
+useAppConfig(
+  level: ConfigLevel,
+  context: AppConfigContext,
+  fetch_config: (level, context) => Promise<AppConfigItem[]>,
+  save_config: (item) => Promise<void>,
+  delete_config: (section, name, level, context) => Promise<void>
+)
+
+// NEW
+useAppConfig(
+  context: AppConfigContext,
+  fetch_config: (context) => Promise<AppConfigItem[]>,
+  save_config: (item) => Promise<void>,
+  delete_config: (section, name, context) => Promise<void>
+)
+```
+
+**Hook Return Value:**
+```typescript
+// OLD
+sections: Record<string, Record<string, string>>
+set_value: (section, key, value: string) => Promise<void>
+
+// NEW
+sections: Record<string, Record<string, AppConfigItem>>  // Full items
+set_value: (section, key, value: string | object, type: ConfigType) => Promise<void>
+change_type: (section, key, new_type: ConfigType) => Promise<void>  // NEW
+```
+
+### 4. Server Action Changes
+
+**Fetch Config:**
+```typescript
+// OLD
+async function fetch_config(
+  level: ConfigLevel,
+  context: AppConfigContext
+): Promise<AppConfigItem[]>
+
+// NEW
+async function fetch_config(
+  context: AppConfigContext
+): Promise<AppConfigItem[]>
+```
+
+**Save Config:**
+```typescript
+// OLD
+const item = {
+  org_id: context.org_id,
+  user_id: level === 'user' ? context.user_id : null,
+  config_value: value
+}
+
+// NEW
+const item = {
+  scope_id: context.scope_id,
+  user_id: context.user_id ?? null,
+  config_value_text: type === 'general' ? value : '',
+  config_value_json: type === 'json' ? value : {},
+  config_type: type
+}
+```
+
+**Delete Config:**
+```typescript
+// OLD
+async function delete_config(
+  section: string,
+  name: string,
+  level: ConfigLevel,
+  context: AppConfigContext
+)
+
+// NEW
+async function delete_config(
+  section: string,
+  name: string,
+  context: AppConfigContext
+)
+```
+
+## Migration Steps
+
+### 1. Database Migration
+
+**PostgreSQL:**
+```sql
+-- Add new columns
+ALTER TABLE hazo_app_config
+  ADD COLUMN scope_id TEXT,
+  ADD COLUMN config_value_text TEXT,
+  ADD COLUMN config_value_json JSONB,
+  ADD COLUMN config_type TEXT;
+
+-- Migrate existing data
+UPDATE hazo_app_config SET
+  scope_id = org_id,
+  config_value_text = config_value,
+  config_value_json = '{}'::jsonb,
+  config_type = 'general';
+
+-- Drop old columns
+ALTER TABLE hazo_app_config
+  DROP COLUMN org_id,
+  DROP COLUMN config_value;
+
+-- Add constraints
+ALTER TABLE hazo_app_config
+  ALTER COLUMN config_type SET NOT NULL,
+  ADD CONSTRAINT check_type_values CHECK (config_type IN ('json', 'general')),
+  ADD CONSTRAINT check_value_exclusivity CHECK (
+    (config_type = 'general' AND config_value_text IS NOT NULL AND config_value_json IS NULL) OR
+    (config_type = 'json' AND config_value_json IS NOT NULL AND config_value_text IS NULL)
+  );
+
+-- Update indexes
+DROP INDEX IF EXISTS idx_hazo_app_config_org;
+DROP INDEX IF EXISTS idx_hazo_app_config_unique;
+
+CREATE INDEX idx_hazo_app_config_scope ON hazo_app_config(scope_id);
+CREATE UNIQUE INDEX idx_hazo_app_config_unique ON hazo_app_config(scope_id, user_id, config_section, config_name);
+```
+
+**SQLite:**
+```sql
+-- SQLite doesn't support dropping columns, so recreate the table
+CREATE TABLE hazo_app_config_new (
+  id TEXT PRIMARY KEY,
+  scope_id TEXT,
+  user_id TEXT,
+  config_section TEXT NOT NULL,
+  config_name TEXT NOT NULL,
+  config_value_text TEXT,
+  config_value_json TEXT,
+  config_type TEXT NOT NULL CHECK (config_type IN ('json', 'general')),
+  created_at TEXT DEFAULT (datetime('now')),
+  changed_at TEXT,
+  CHECK (
+    (config_type = 'general' AND config_value_text IS NOT NULL AND config_value_json IS NULL) OR
+    (config_type = 'json' AND config_value_json IS NOT NULL AND config_value_text IS NULL)
+  )
+);
+
+-- Migrate data
+INSERT INTO hazo_app_config_new (id, scope_id, user_id, config_section, config_name, config_value_text, config_value_json, config_type, created_at, changed_at)
+SELECT id, org_id, user_id, config_section, config_name, config_value, NULL, 'general', created_at, changed_at
+FROM hazo_app_config;
+
+-- Replace old table
+DROP TABLE hazo_app_config;
+ALTER TABLE hazo_app_config_new RENAME TO hazo_app_config;
+
+-- Recreate indexes
+CREATE INDEX idx_hazo_app_config_scope ON hazo_app_config(scope_id);
+CREATE INDEX idx_hazo_app_config_user ON hazo_app_config(user_id);
+CREATE UNIQUE INDEX idx_hazo_app_config_unique ON hazo_app_config(scope_id, user_id, config_section, config_name);
+```
+
+### 2. Code Migration
+
+**Update Component Usage:**
+```typescript
+// OLD
+import { AppConfig } from 'hazo_config/components'
+
+<AppConfig
+  level="org"
+  context={{ org_id: DEMO_ORG_ID }}
+  fetch_config={fetch_config}
+  save_config={save_config}
+  delete_config={delete_config}
+/>
+
+// NEW
+import { AppConfig } from 'hazo_config/components'
+
+<AppConfig
+  title="Scope Settings"
+  context={{ scope_id: DEMO_SCOPE_ID }}
+  fetch_config={fetch_config}
+  save_config={save_config}
+  delete_config={delete_config}
+/>
+```
+
+**Update Server Actions:**
+```typescript
+// OLD
+export async function fetch_config(
+  level: ConfigLevel,
+  context: AppConfigContext
+): Promise<AppConfigItem[]> {
+  const query = new QueryBuilder()
+    .from('hazo_app_config')
+    .where('org_id', 'eq', context.org_id)
+
+  if (level === 'org') {
+    query.where('user_id', 'is', null)
+  } else {
+    query.where('user_id', 'eq', context.user_id)
+  }
+
+  return await hazo.query(query)
+}
+
+// NEW
+export async function fetch_config(
+  context: AppConfigContext
+): Promise<AppConfigItem[]> {
+  const query = new QueryBuilder()
+    .from('hazo_app_config')
+    .where('scope_id', 'eq', context.scope_id)
+
+  if (context.user_id) {
+    query.where('user_id', 'eq', context.user_id)
+  } else {
+    query.where('user_id', 'is', null)
+  }
+
+  const result = await hazo.query(query)
+
+  // Parse JSON for SQLite (stored as TEXT)
+  return result.map(item => ({
+    ...item,
+    config_value_json: item.config_value_json
+      ? JSON.parse(item.config_value_json)
+      : {}
+  }))
+}
+
+export async function save_config(
+  item: Omit<AppConfigItem, 'id' | 'created_at' | 'changed_at'>
+): Promise<void> {
+  // Validate mutual exclusivity
+  if (item.config_type === 'general' && !item.config_value_text) {
+    throw new Error('General type requires config_value_text')
+  }
+  if (item.config_type === 'json' && !item.config_value_json) {
+    throw new Error('JSON type requires config_value_json')
+  }
+
+  // For SQLite: stringify JSON
+  const db_data = {
+    config_value_text: item.config_type === 'general' ? item.config_value_text : null,
+    config_value_json: item.config_type === 'json'
+      ? JSON.stringify(item.config_value_json)
+      : null,
+    config_type: item.config_type,
+  }
+
+  // ... rest of save logic
+}
+
+export async function delete_config(
+  section: string,
+  name: string,
+  context: AppConfigContext
+): Promise<void> {
+  const query = new QueryBuilder()
+    .from('hazo_app_config')
+    .where('scope_id', 'eq', context.scope_id)
+    .where('config_section', 'eq', section)
+    .where('config_name', 'eq', name)
+
+  if (context.user_id) {
+    query.where('user_id', 'eq', context.user_id)
+  } else {
+    query.where('user_id', 'is', null)
+  }
+
+  await hazo.query(query, 'DELETE')
+}
+```
+
+**Update Hook Usage:**
+```typescript
+// OLD
+const {
+  sections,
+  set_value,
+  delete_value
+} = useAppConfig('org', context, fetch_config, save_config, delete_config)
+
+// Access value
+const value = sections.general.company_name  // string
+
+// Set value
+await set_value('general', 'company_name', 'New Name')
+
+// NEW
+const {
+  sections,
+  set_value,
+  delete_value,
+  change_type
+} = useAppConfig(context, fetch_config, save_config, delete_config)
+
+// Access value
+const item = sections.general.company_name  // AppConfigItem
+const value = item.config_type === 'json'
+  ? item.config_value_json
+  : item.config_value_text
+
+// Set general value
+await set_value('general', 'company_name', 'New Name', 'general')
+
+// Set JSON value
+await set_value('features', 'flags', { beta: true }, 'json')
+
+// Change type
+await change_type('general', 'company_name', 'json')
+```
+
+### 3. Import Updates
+
+**Type Imports:**
+```typescript
+// OLD
+import type { ConfigLevel, AppConfigItem } from 'hazo_config'
+
+// NEW
+import type { ConfigType, AppConfigItem } from 'hazo_config'
+```
+
+## New Features in v2
+
+### 1. JSON Configuration Values
+
+You can now store structured configuration as JSON:
+
+```typescript
+await set_value('features', 'enabled_features', {
+  analytics: true,
+  notifications: false,
+  api_access: true
+}, 'json')
+
+await set_value('branding', 'theme_config', {
+  dark_mode: true,
+  accent_color: '#3B82F6',
+  font: 'Inter'
+}, 'json')
+```
+
+### 2. Type Conversion
+
+Convert between general and JSON types:
+
+```typescript
+// Convert text to JSON
+await change_type('general', 'settings', 'json')
+// Will try JSON.parse(), fallback to { value: text }
+
+// Convert JSON to text
+await change_type('features', 'flags', 'general')
+// Will JSON.stringify() the object
+```
+
+### 3. UI Enhancements
+
+- Type badge showing 'json' or 'general'
+- JSON editor with syntax validation
+- Type change button with confirmation
+- Type selector when adding new keys
+
+## Testing Migration
+
+Before migrating production:
+
+1. **Backup your database**
+2. **Test migration on a copy:**
+   ```bash
+   # PostgreSQL
+   pg_dump production_db > backup.sql
+   createdb test_db
+   psql test_db < backup.sql
+   # Run migration scripts on test_db
+   ```
+
+3. **Update and test your application:**
+   ```bash
+   npm install hazo_config@^2.0.0
+   npm run build
+   npm test
+   ```
+
+4. **Verify data integrity:**
+   - All `config_value` migrated to `config_value_text`
+   - All items have `config_type = 'general'`
+   - All items have `scope_id` matching old `org_id`
+   - Unique constraints still enforced
+
+## Rollback Plan
+
+If you need to rollback:
+
+```sql
+-- PostgreSQL
+ALTER TABLE hazo_app_config
+  ADD COLUMN org_id TEXT,
+  ADD COLUMN config_value TEXT;
+
+UPDATE hazo_app_config SET
+  org_id = scope_id,
+  config_value = COALESCE(config_value_text, config_value_json::text);
+
+ALTER TABLE hazo_app_config
+  DROP COLUMN scope_id,
+  DROP COLUMN config_value_text,
+  DROP COLUMN config_value_json,
+  DROP COLUMN config_type;
+```
+
+## Support
+
+For migration assistance:
+- File an issue: https://github.com/pub12/hazo_config/issues
+- Email: support@example.com
+
+## Version History
+
+- **v2.0.0**: Schema migration (scope_id, JSON support)
+- **v1.4.2**: Last version before breaking changes