@jmruthers/pace-core 0.5.189 → 0.5.191

package/docs/migration/person-scoped-profiles-migration-guide.md

@@ -0,0 +1,472 @@
+# Person-Scoped Profiles Migration Guide
+
+**Version:** 0.5.190+  
+**Migration Date:** 2025-12-05  
+**Breaking Changes:** Yes
+
+## Overview
+
+Profiles (membership, medical, and contact) have been migrated from **organisation-scoped** to **person-scoped**. Each person now has:
+
+- **One membership profile** (`pace_member`) - regardless of organisation
+- **One medical profile** (`medi_profile`) - regardless of organisation  
+- **Multiple contact profiles** (`pace_contact`) - person-scoped, multiple per type allowed
+
+This change means profiles are no longer tied to specific organisations and are shared across all organisations a person belongs to.
+
+## What Changed
+
+### Tables Modified
+
+#### 1. `pace_member`
+- **Removed:** `organisation_id` column
+- **Added:** Unique constraint on `person_id` (one membership per person)
+- **Impact:** A person can now only have ONE membership record, regardless of how many organisations they belong to
+
+#### 2. `medi_profile`
+- **Removed:** `organisation_id` column
+- **Impact:** One medical profile per person (via member relationship)
+
+#### 3. `pace_contact`
+- **Removed:** `organisation_id` and `member_id` columns
+- **Added:** `person_id` column (NOT NULL, FK to `pace_person`)
+- **Impact:** Contacts are now directly linked to persons, not members
+
+#### 4. Related Tables (organisation_id removed)
+- `medi_condition`
+- `medi_diet`
+- `medi_action_plan`
+- `medi_profile_versions`
+- `pace_consent`
+- `pace_identification`
+- `pace_qualification`
+
+### RLS Policy Changes
+
+All RLS policies for these tables have been updated to:
+- Remove organisation-based access checks
+- Use person-scoped access control instead
+- Allow access based on person ownership, not organisation membership
+
+## Breaking Changes
+
+### 1. Queries Filtering by `organisation_id`
+
+**Before:**
+```typescript
+// ❌ This will fail - organisation_id column no longer exists
+const { data } = await supabase
+  .from('pace_member')
+  .select('*')
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+// ✅ Filter by person_id instead
+const { data } = await supabase
+  .from('pace_member')
+  .select('*')
+  .eq('person_id', personId);
+```
+
+### 2. Joins Using `organisation_id`
+
+**Before:**
+```typescript
+// ❌ This will fail
+const { data } = await supabase
+  .from('pace_member')
+  .select('*, organisations(*)')
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+// ✅ Join via person → user → organisation memberships
+const { data } = await supabase
+  .from('pace_member')
+  .select('*, pace_person(*, user_profiles(*))')
+  .eq('person_id', personId);
+```
+
+### 3. Contact Queries Using `member_id`
+
+**Before:**
+```typescript
+// ❌ This will fail - member_id column no longer exists
+const { data } = await supabase
+  .from('pace_contact')
+  .select('*')
+  .eq('member_id', memberId);
+```
+
+**After:**
+```typescript
+// ✅ Use person_id instead
+const { data } = await supabase
+  .from('pace_contact')
+  .select('*')
+  .eq('person_id', personId);
+```
+
+### 4. Insert/Update Operations
+
+**Before:**
+```typescript
+// ❌ This will fail - organisation_id required
+await supabase
+  .from('pace_member')
+  .insert({
+    person_id: personId,
+    organisation_id: orgId, // ❌ Column doesn't exist
+    membership_number: '12345'
+  });
+```
+
+**After:**
+```typescript
+// ✅ No organisation_id needed
+await supabase
+  .from('pace_member')
+  .insert({
+    person_id: personId,
+    membership_number: '12345'
+  });
+```
+
+## Impact Assessment Checklist
+
+Use this checklist to identify areas in your app that need updates:
+
+### Database Queries
+
+- [ ] Search codebase for `pace_member` queries filtering by `organisation_id`
+- [ ] Search codebase for `medi_profile` queries filtering by `organisation_id`
+- [ ] Search codebase for `pace_contact` queries using `member_id`
+- [ ] Search codebase for `pace_consent` queries filtering by `organisation_id`
+- [ ] Search codebase for `pace_identification` queries filtering by `organisation_id`
+- [ ] Search codebase for `pace_qualification` queries filtering by `organisation_id`
+- [ ] Search codebase for `medi_condition`, `medi_diet`, `medi_action_plan` queries filtering by `organisation_id`
+
+### TypeScript Types
+
+- [ ] Update TypeScript types (regenerate from database schema)
+- [ ] Remove `organisation_id` from type definitions for profile tables
+- [ ] Update `pace_contact` types to use `person_id` instead of `member_id`
+
+### UI Components
+
+- [ ] Review profile display components - remove organisation context assumptions
+- [ ] Update forms that create/edit profiles - remove organisation_id fields
+- [ ] Update contact management - use person_id instead of member_id
+- [ ] Review profile selection/filtering UI - remove organisation filters
+
+### Business Logic
+
+- [ ] Review code that assumes multiple memberships per person
+- [ ] Update logic that creates profiles per organisation
+- [ ] Review permission checks that rely on organisation_id for profiles
+- [ ] Update any code that merges/duplicates profiles across organisations
+
+### Data Access Patterns
+
+- [ ] Review use of `useSecureDataAccess` hook with profile tables
+- [ ] Update any custom data access utilities
+- [ ] Review RPC functions that query profile tables
+
+## Code Migration Examples
+
+### Example 1: Fetching Member Profile
+
+**Before:**
+```typescript
+async function getMemberProfile(personId: string, orgId: string) {
+  const { data } = await supabase
+    .from('pace_member')
+    .select('*')
+    .eq('person_id', personId)
+    .eq('organisation_id', orgId) // ❌
+    .single();
+  return data;
+}
+```
+
+**After:**
+```typescript
+async function getMemberProfile(personId: string) {
+  // ✅ No organisation_id needed - one profile per person
+  const { data } = await supabase
+    .from('pace_member')
+    .select('*')
+    .eq('person_id', personId)
+    .single();
+  return data;
+}
+```
+
+### Example 2: Fetching Contacts
+
+**Before:**
+```typescript
+async function getContacts(memberId: string) {
+  const { data } = await supabase
+    .from('pace_contact')
+    .select('*')
+    .eq('member_id', memberId) // ❌
+    .eq('organisation_id', orgId); // ❌
+  return data;
+}
+```
+
+**After:**
+```typescript
+async function getContacts(personId: string) {
+  // ✅ Use person_id directly
+  const { data } = await supabase
+    .from('pace_contact')
+    .select('*')
+    .eq('person_id', personId);
+  return data;
+}
+```
+
+### Example 3: Creating Medical Profile
+
+**Before:**
+```typescript
+async function createMedicalProfile(memberId: string, orgId: string, data: MedicalData) {
+  const { data: profile } = await supabase
+    .from('medi_profile')
+    .insert({
+      member_id: memberId,
+      organisation_id: orgId, // ❌
+      ...data
+    })
+    .select()
+    .single();
+  return profile;
+}
+```
+
+**After:**
+```typescript
+async function createMedicalProfile(memberId: string, data: MedicalData) {
+  // ✅ No organisation_id needed
+  const { data: profile } = await supabase
+    .from('medi_profile')
+    .insert({
+      member_id: memberId,
+      ...data
+    })
+    .select()
+    .single();
+  return profile;
+}
+```
+
+### Example 4: Getting Person's Member in Organisation Context
+
+**Before:**
+```typescript
+// ❌ This pattern no longer works
+const member = await getMemberForPersonInOrg(personId, orgId);
+```
+
+**After:**
+```typescript
+// ✅ Get the person's single membership
+const { data: member } = await supabase
+  .from('pace_member')
+  .select('*')
+  .eq('person_id', personId)
+  .single();
+
+// If you need to check organisation access, check via rbac_organisation_roles
+const { data: orgRoles } = await supabase
+  .from('rbac_organisation_roles')
+  .select('organisation_id')
+  .eq('user_id', userId)
+  .eq('organisation_id', orgId)
+  .eq('status', 'active');
+```
+
+## Testing Recommendations
+
+### 1. Unit Tests
+
+- [ ] Update test fixtures to remove `organisation_id` from profile records
+- [ ] Update mock data generators
+- [ ] Fix tests that assert organisation_id values
+
+### 2. Integration Tests
+
+- [ ] Test profile creation without organisation_id
+- [ ] Test profile queries by person_id
+- [ ] Test contact management with person_id
+- [ ] Verify RLS policies work correctly
+
+### 3. E2E Tests
+
+- [ ] Test profile display across different organisations
+- [ ] Verify profiles are shared correctly
+- [ ] Test contact management flows
+- [ ] Verify permission checks still work
+
+### 4. Data Validation
+
+- [ ] Verify no duplicate memberships exist per person
+- [ ] Verify medical profiles are correctly linked
+- [ ] Verify contacts are correctly migrated to person_id
+
+## Common Patterns to Update
+
+### Pattern 1: Organisation-Scoped Profile Lists
+
+**Before:**
+```typescript
+// Get all members in an organisation
+const { data } = await supabase
+  .from('pace_member')
+  .select('*')
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+// Get all members in an organisation via person → user → org roles
+const { data: orgMembers } = await supabase
+  .from('rbac_organisation_roles')
+  .select(`
+    organisation_id,
+    user_id,
+    pace_person!inner(
+      id,
+      pace_member(*)
+    )
+  `)
+  .eq('organisation_id', orgId)
+  .eq('status', 'active');
+```
+
+### Pattern 2: Profile Existence Checks
+
+**Before:**
+```typescript
+// Check if member exists in organisation
+const { data } = await supabase
+  .from('pace_member')
+  .select('id')
+  .eq('person_id', personId)
+  .eq('organisation_id', orgId)
+  .single();
+```
+
+**After:**
+```typescript
+// Check if person has a membership (regardless of org)
+const { data } = await supabase
+  .from('pace_member')
+  .select('id')
+  .eq('person_id', personId)
+  .single();
+```
+
+### Pattern 3: Profile Creation with Organisation Context
+
+**Before:**
+```typescript
+// Create profile for person in organisation
+await supabase
+  .from('pace_member')
+  .insert({
+    person_id: personId,
+    organisation_id: orgId,
+    membership_number: generateNumber()
+  });
+```
+
+**After:**
+```typescript
+// Create profile for person (one per person, not per org)
+// Check if already exists first
+const { data: existing } = await supabase
+  .from('pace_member')
+  .select('id')
+  .eq('person_id', personId)
+  .single();
+
+if (!existing) {
+  await supabase
+    .from('pace_member')
+    .insert({
+      person_id: personId,
+      membership_number: generateNumber()
+    });
+}
+```
+
+## TypeScript Type Updates
+
+After applying migrations, regenerate your database types:
+
+```bash
+npx supabase gen types typescript --project-id <your-project-id> > src/types/database.generated.ts
+```
+
+The updated types will reflect:
+- Removed `organisation_id` from profile tables
+- `pace_contact` using `person_id` instead of `member_id`
+- Updated relationships
+
+## RLS Policy Behavior
+
+RLS policies now work as follows:
+
+1. **Person Ownership**: Users can access profiles for persons they own (via `pace_person.user_id`)
+2. **Contact Permissions**: Users can access contacts where they are the contact person or own the person
+3. **No Organisation Filtering**: Profiles are accessible regardless of organisation context
+4. **Super Admin Override**: Super admins can access all profiles
+
+## Migration Support
+
+If you encounter issues:
+
+1. **Check Migration Status**: Verify all migrations are applied
+2. **Verify Types**: Regenerate TypeScript types from current schema
+3. **Review RLS**: Ensure RLS policies are correctly applied
+4. **Check Logs**: Review Supabase logs for RLS policy violations
+
+## RPC Functions Updated
+
+The following RPC functions have been updated to work with person-scoped profiles:
+
+- **`data_pace_linked_profiles_list`** - Now uses `person_id` from `pace_contact` instead of `member_id`
+- **`data_pace_contacts_list`** - Now uses `person_id` from `pace_contact` instead of `member_id`
+- **`data_pace_contact_get`** - Now uses `person_id` from `pace_contact` instead of `member_id`
+
+These functions now:
+- Join `pace_contact` via `person_id` instead of `member_id`
+- Get `member_id` from `pace_member` via `person_id` join
+- Get `organisation_id` from user's organisation roles (since profiles are no longer organisation-scoped)
+
+If you have custom RPC functions that reference `pace_contact.member_id` or profile table `organisation_id` columns, you'll need to update them similarly.
+
+## Questions?
+
+For questions or issues related to this migration:
+- Review the migration files in `supabase/migrations/`
+- Check RLS policy definitions in the migration files
+- Review the pace-core documentation for updated API patterns
+- Check for custom RPC functions that may need updates
+
+## Summary
+
+**Key Takeaways:**
+- Profiles are now person-scoped, not organisation-scoped
+- Remove all `organisation_id` filters/queries for profile tables
+- Use `person_id` instead of `member_id` for contacts
+- One membership per person (enforced by unique constraint)
+- Update all TypeScript types after migration
+- Test thoroughly, especially cross-organisation scenarios
+

package/docs/rbac/compliance/compliance-guide.md

@@ -152,7 +152,7 @@ import { createClient } from '@supabase/supabase-js';
 
 const supabase = createClient(
   import.meta.env.VITE_SUPABASE_URL,
-  import.meta.env.VITE_SUPABASE_ANON_KEY
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 );
 
 // ⚠️ REQUIRED: Call setupRBAC before rendering
@@ -266,7 +266,7 @@ import { createClient } from '@supabase/supabase-js';
 
 export const supabase = createClient(
   import.meta.env.VITE_SUPABASE_URL,
-  import.meta.env.VITE_SUPABASE_ANON_KEY
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 );
 ```
 

package/docs/rbac/event-based-apps.md

@@ -89,7 +89,7 @@ Create `.env.local`:
 ```bash
 # .env.local
 VITE_SUPABASE_URL=https://your-project.supabase.co
-VITE_SUPABASE_ANON_KEY=your-anon-key-here
+VITE_SUPABASE_PUBLISHABLE_KEY=your-publishable-key-here
 VITE_APP_NAME=pace-trac
 ```
 
@@ -225,7 +225,7 @@ Create `src/lib/supabase.ts`:
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
 if (!supabaseUrl || !supabaseAnonKey) {
   throw new Error('Missing Supabase environment variables')

package/docs/rbac/getting-started.md

@@ -99,7 +99,7 @@ import '@jmruthers/pace-core/src/styles/core.css';
 // Initialize Supabase
 const supabase = createClient(
   import.meta.env.VITE_SUPABASE_URL!,
-  import.meta.env.VITE_SUPABASE_ANON_KEY!
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!
 );
 
 // ⚠️ REQUIRED: Setup RBAC before rendering
@@ -258,7 +258,7 @@ import App from './App';
 // Initialize Supabase
 const supabase = createClient(
   import.meta.env.VITE_SUPABASE_URL!,
-  import.meta.env.VITE_SUPABASE_ANON_KEY!
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!
 );
 
 // ⚠️ REQUIRED: Setup RBAC before rendering

package/docs/rbac/quick-start.md

@@ -88,7 +88,7 @@ Create `.env.local`:
 # .env.local
 VITE_SUPABASE_URL=https://your-project.supabase.co
 # Accepts both legacy anon keys and modern publishable keys (sb_publishable_...)
-VITE_SUPABASE_ANON_KEY=your-publishable-key-or-anon-key-here
+VITE_SUPABASE_PUBLISHABLE_KEY=your-publishable-key-here
 VITE_APP_NAME=user-manager
 ```
 
@@ -213,7 +213,7 @@ Create `src/lib/supabase.ts`:
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
 if (!supabaseUrl || !supabaseAnonKey) {
   throw new Error('Missing Supabase environment variables')

package/docs/security/README.md

@@ -139,10 +139,10 @@ function ProtectedComponent() {
 
 ### 3. Inactivity Auto-Logout
 
-PACE Core includes built-in inactivity tracking for enhanced security:
+PACE Core includes built-in inactivity tracking for enhanced security. **All inactivity timeout props are mandatory** - apps must explicitly configure them:
 
-- **Automatic logout** after 30 minutes of inactivity (configurable)
-- **Warning modal** appears 60 seconds before logout
+- **Automatic logout** after configured period of inactivity (must be configured)
+- **Warning modal** appears before logout (must be configured)
 - **Cross-tab synchronization** - activity in any tab resets the timer
 - **Persistence** - survives page reloads and browser restarts
 - **Production-safe** - cannot be disabled in production builds
@@ -597,7 +597,7 @@ Secure configuration using environment variables:
 ```bash
 # Authentication
 VITE_SUPABASE_URL=your_supabase_url
-VITE_SUPABASE_ANON_KEY=your_anon_key
+VITE_SUPABASE_PUBLISHABLE_KEY=your_publishable_key
 VITE_SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
 
 # Security