@jmruthers/pace-core 0.5.190 → 0.5.193

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/event-based-apps.md

@@ -29,7 +29,9 @@ A simple event management app that demonstrates:
 4. **ALWAYS set up providers correctly** in the exact order shown below
 5. **Use the exact app name** from your environment variable (must match database exactly, case-sensitive)
 6. **Ensure database setup is complete** before starting the app - App must be registered with `requires_event = true`
-7. **User must have organisation role** - Users need roles assigned in `rbac_organisation_roles` table
+7. **User must have organisation role OR event access** - Users need either:
+   - Explicit roles in `rbac_organisation_roles` table, OR
+   - Event access via `rbac_event_app_roles` (organisation access is automatically inferred)
 8. **Event must be selected** - `selectedEventId` must be set in UnifiedAuth context before permission checks
 9. **Event must belong to organisation** - The event's `organisation_id` must match the user's organisation
 
@@ -200,6 +202,8 @@ RETURNING event_id, event_name, event_code, organisation_id;
 
 #### 5.5 Assign User Roles
 
+**Option 1: Explicit Organisation Membership (Traditional)**
+
 ```sql
 -- Grant a user the org_admin role (replace with actual user and organisation IDs)
 INSERT INTO rbac_organisation_roles (user_id, organisation_id, role, status, granted_at)
@@ -216,6 +220,42 @@ ON CONFLICT (user_id, organisation_id) DO UPDATE SET
   updated_at = NOW();
 ```
 
+**Option 2: Event-Based Access (Automatic Organisation Inference)**
+
+For event-based apps, you can grant access via event roles. The system will automatically infer organisation access from event access:
+
+```sql
+-- Grant a user event access (organisation access is automatically inferred)
+-- Replace with actual user, event, app, and organisation IDs
+INSERT INTO rbac_event_app_roles (
+  user_id, 
+  event_id, 
+  app_id, 
+  organisation_id,
+  role, 
+  status, 
+  granted_at
+)
+VALUES (
+  'your-user-id'::uuid,
+  'your-event-id'::text,
+  (SELECT id FROM rbac_apps WHERE name = 'pace-trac'),
+  'your-organisation-id'::uuid,  -- Must match event's organisation_id
+  'planner',  -- or 'event_admin', 'participant', etc.
+  'active',
+  NOW()
+)
+ON CONFLICT (user_id, event_id, app_id, role) DO UPDATE SET
+  status = EXCLUDED.status,
+  updated_at = NOW();
+```
+
+**Important Notes:**
+- When a user has event access via `rbac_event_app_roles`, they automatically get implicit organisation access
+- The system grants an implicit 'member' role for permission checks
+- Explicit organisation memberships take precedence over inferred access
+- This eliminates the need to maintain duplicate organisation memberships for event-only users
+
 ### 6. Create Supabase Client
 
 Create `src/lib/supabase.ts`:
@@ -640,7 +680,9 @@ Your event-based RBAC setup is working correctly if:
 - [ ] App is registered in `rbac_apps` table with `requires_event = true` and `is_active = true`
 - [ ] Pages exist in `rbac_app_pages` for your app
 - [ ] Page permissions exist in `rbac_page_permissions` for your pages, roles, and organisation
-- [ ] User has an active role in `rbac_organisation_roles` for the organisation
+- [ ] User has either:
+  - An active role in `rbac_organisation_roles` for the organisation, OR
+  - Event access via `rbac_event_app_roles` (organisation access is automatically inferred)
 - [ ] At least one event exists in the `event` table for your organisation
 - [ ] `VITE_APP_NAME` environment variable matches database `rbac_apps.name` exactly
 - [ ] `EventProvider` wraps your app content
@@ -762,15 +804,40 @@ WHERE event_id = 'your-event-id'::uuid;
    ```
    - Must have pages for `dashboard`, `participants`, etc.
 
-5. **Verify user has organisation role**:
+5. **Verify user has organisation role OR event access**:
    ```sql
-   SELECT ror.*, u.email
+   -- Check explicit organisation roles
+   SELECT ror.*, u.email, 'explicit' as access_type
    FROM rbac_organisation_roles ror
    JOIN auth.users u ON ror.user_id = u.id
    WHERE ror.user_id = 'your-user-id'::uuid 
-     AND ror.status = 'active';
+     AND ror.status = 'active'
+   
+   UNION ALL
+   
+   -- Check event-based access (which infers organisation access)
+   SELECT 
+     rear.id,
+     rear.user_id,
+     e.organisation_id as organisation_id,
+     'member' as role,  -- Implicit role granted from event access
+     rear.status,
+     rear.granted_at,
+     rear.granted_by,
+     rear.revoked_at,
+     rear.revoked_by,
+     u.email,
+     'inferred' as access_type
+   FROM rbac_event_app_roles rear
+   JOIN event e ON e.event_id = rear.event_id
+   JOIN auth.users u ON rear.user_id = u.id
+   WHERE rear.user_id = 'your-user-id'::uuid 
+     AND rear.status = 'active'
+     AND e.organisation_id = 'your-organisation-id'::uuid;
    ```
-   - User must have at least one active role
+   - User must have either:
+     - At least one active explicit organisation role, OR
+     - Event access via `rbac_event_app_roles` (organisation access is automatically inferred)
    - Must be for the organisation that owns the event
 
 6. **Verify event belongs to user's organisation**:
@@ -847,8 +914,59 @@ WHERE event_id = 'your-event-id'::uuid;
 | **Context Required** | `organisationId` | `eventId` (org auto-resolved) |
 | **PagePermissionGuard** | Needs `organisationId` | Needs `eventId` (org auto-resolved) |
 | **Scope Resolution** | Direct from context | Organisation resolved from event |
+| **User Access** | Requires explicit `rbac_organisation_roles` | Can use `rbac_event_app_roles` (org access inferred) |
 | **Use Case** | User management, org settings | Event registration, event management |
 
+## 🎯 Organisation Access Inference from Events
+
+**New Feature:** The RBAC system can now automatically infer organisation access from event access, eliminating the need for explicit organisation memberships when users have event access.
+
+### How It Works
+
+1. **User has event access** via `rbac_event_app_roles` table
+2. **System derives organisation** from the event's `organisation_id`
+3. **System grants implicit 'member' role** for permission checks
+4. **Permission checks proceed** as if user had explicit organisation membership
+
+### Benefits
+
+- **Eliminates data duplication** - No need to maintain both event and organisation memberships
+- **Simplifies onboarding** - Grant event access, organisation access is automatic
+- **Maintains security** - Still validates that user has valid event access
+- **Backward compatible** - Explicit organisation memberships still work and take precedence
+
+### Example
+
+```sql
+-- User has event access but no explicit organisation membership
+INSERT INTO rbac_event_app_roles (
+  user_id, 
+  event_id, 
+  app_id, 
+  organisation_id,
+  role, 
+  status
+)
+VALUES (
+  'user-123'::uuid,
+  'event-456'::text,
+  (SELECT id FROM rbac_apps WHERE name = 'pace-trac'),
+  'org-789'::uuid,
+  'planner',
+  'active'
+);
+
+-- System automatically allows organisation access for permission checks
+-- User can now access pages that require organisation context
+-- Implicit role: 'member' (for permission matching)
+```
+
+### When Explicit Membership is Still Required
+
+- Users who need organisation-level access without event context
+- Users who need specific organisation roles (org_admin, leader) that aren't granted via events
+- Organisation management features that don't require event context
+
 ## 🚀 Next Steps
 
 - **[RBAC Overview](./README.md)** - Complete RBAC system documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.190",
+  "version": "0.5.193",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {