@jmruthers/pace-core 0.5.193 → 0.6.2

package/src/rbac/secureClient.ts

@@ -19,26 +19,44 @@ import { OrganisationContextRequiredError } from './types';
  * This client automatically injects organisation context into all requests
  * and prevents queries that don't have the required context.
  * 
- * Note: Callers should derive organisationId from eventId before creating this client
- * if working with event-required apps. The client requires organisationId.
+ * Note: For non-super-admins, organisationId is required. Super-admins can operate
+ * without organisationId to access system-wide tables (like core_organisations).
+ * Callers should derive organisationId from eventId before creating this client
+ * if working with event-required apps.
  */
 export class SecureSupabaseClient {
   private supabase: SupabaseClient<Database>;
   private edgeFunctionClient: SupabaseClient<Database> | null = null;
   private supabaseUrl: string;
   private supabaseKey: string;
-  private organisationId: UUID;
+  private organisationId: UUID | null;
   private eventId?: string;
   private appId?: UUID;
   private isSuperAdmin: boolean;
+  private usesExistingClient: boolean = false;
+
+  /**
+   * RPC functions that are safe to call without organisation context.
+   *
+   * These functions must:
+   * - rely on JWT context (auth.uid()) for authentication
+   * - not read or write organisation-scoped data
+   *
+   * This allowlist enables compliant consuming apps to use `secureSupabase.rpc(...)`
+   * even before an organisation is selected (common during initial page load/refresh).
+   */
+  private static readonly GLOBAL_RPC_ALLOWLIST = new Set<string>([
+    'data_rbac_apps_list',
+  ]);
 
   constructor(
     supabaseUrl: string,
     supabaseKey: string,
-    organisationId: UUID,
+    organisationId: UUID | null,
     eventId?: string,
     appId?: UUID,
-    isSuperAdmin: boolean = false
+    isSuperAdmin: boolean = false,
+    existingClient?: SupabaseClient<Database>
   ) {
     this.supabaseUrl = supabaseUrl;
     this.supabaseKey = supabaseKey;
@@ -47,18 +65,25 @@ export class SecureSupabaseClient {
     this.appId = appId;
     this.isSuperAdmin = isSuperAdmin;
 
-    // Create the base Supabase client with context headers
-    // Note: We'll override functions.invoke to exclude headers for Edge Functions
-    // as they may not have CORS configured to accept custom headers
-    this.supabase = createClient<Database>(supabaseUrl, supabaseKey, {
-      global: {
-        headers: {
-          'x-organisation-id': organisationId,
-          'x-event-id': eventId || '',
-          'x-app-id': appId || '',
+    // Prefer reusing an existing authenticated client (avoids multiple GoTrue instances
+    // and ensures auth context is present for RLS policies).
+    if (existingClient) {
+      this.supabase = existingClient;
+      this.usesExistingClient = true;
+    } else {
+      // Create the base Supabase client with context headers
+      // Note: We'll override functions.invoke to exclude headers for Edge Functions
+      // as they may not have CORS configured to accept custom headers
+      this.supabase = createClient<Database>(supabaseUrl, supabaseKey, {
+        global: {
+          headers: {
+            'x-organisation-id': organisationId || '',
+            'x-event-id': eventId || '',
+            'x-app-id': appId || '',
+          },
         },
-      },
-    });
+      });
+    }
 
     // Override the auth methods to inject context
     this.setupContextInjection();
@@ -75,8 +100,10 @@ export class SecureSupabaseClient {
     const originalFrom = this.supabase.from.bind(this.supabase);
     
     (this.supabase as any).from = (table: string): any => {
-      // Validate context before allowing any database operations
-      this.validateContext();
+      // Validate context before allowing database operations.
+      // Some tables are not organisation-scoped (e.g. rbac_apps) and must be queryable
+      // without organisation context for initial bootstrapping.
+      this.validateContextForTable(table);
       
       // Type assertion needed because table is a string but Supabase expects specific table names
       const query = originalFrom(table as any);
@@ -94,15 +121,25 @@ export class SecureSupabaseClient {
     // Type assertion needed because we're wrapping the generic rpc method
     // The fn parameter is typed as string to match Supabase's rpc signature
     (this.supabase as any).rpc = (fn: string, args?: any, options?: any): any => {
-      // Validate context before allowing any RPC calls
-      this.validateContext();
+      // Validate context before allowing RPC calls.
+      // Some RPCs are global (not organisation-scoped) but still require auth.uid() from JWT.
+      // Allow these even without organisation context.
+      this.validateContextForRpc(fn);
       
       // Inject context into RPC calls
+      // Only include organisation_id if it's available (super-admins may not have it)
+      // IMPORTANT:
+      // Do NOT overwrite explicitly provided RPC parameters.
+      // Some RPCs legitimately take `p_app_id`/`p_event_id` as the *target* entity,
+      // which may differ from the current RBAC scope app/event.
+      const safeArgs = (args ?? {}) as Record<string, unknown>;
       const contextArgs = {
-        ...args,
-        p_organisation_id: this.organisationId,
-        p_event_id: this.eventId,
-        p_app_id: this.appId,
+        ...safeArgs,
+        ...(this.organisationId && safeArgs.p_organisation_id === undefined
+          ? { p_organisation_id: this.organisationId }
+          : {}),
+        ...(this.eventId && safeArgs.p_event_id === undefined ? { p_event_id: this.eventId } : {}),
+        ...(this.appId && safeArgs.p_app_id === undefined ? { p_app_id: this.appId } : {}),
       };
       
       return originalRpc(fn as any, contextArgs, options);
@@ -119,10 +156,19 @@ export class SecureSupabaseClient {
    * This avoids interfering with the main client's operations.
    */
   private setupEdgeFunctionHandling() {
-    // Create a separate client without custom headers for Edge Functions
-    // This prevents CORS errors when Edge Functions don't accept custom headers
-    // Store it as an instance variable to avoid creating multiple clients
-    // We'll use this client directly for Edge Function calls instead of overriding
+    // IMPORTANT:
+    // Do not create a second Supabase client when we are already reusing an authenticated
+    // base client (this triggers "Multiple GoTrueClient instances" warnings and can cause
+    // session/auth desync that breaks RLS-protected reads).
+    //
+    // If we're using an existing client, just use it for Edge Functions too.
+    if (this.usesExistingClient) {
+      this.edgeFunctionClient = null;
+      return;
+    }
+
+    // Otherwise, create a separate client without the custom RBAC headers for Edge Functions.
+    // This prevents CORS errors when Edge Functions don't accept custom headers.
     this.edgeFunctionClient = createClient<Database>(this.supabaseUrl, this.supabaseKey);
   }
 
@@ -173,13 +219,28 @@ export class SecureSupabaseClient {
           return originalInsert(values);
         }
         // Non-super-admin: Add organisation_id as defense in depth
+        // organisationId should always be available for non-super-admins (validateContext ensures this)
+        if (!this.organisationId) {
+          throw new OrganisationContextRequiredError();
+        }
         const contextValues = Array.isArray(values) 
           ? values.map(v => ({ ...v, organisation_id: this.organisationId }))
           : { ...values, organisation_id: this.organisationId };
         return originalInsert(contextValues);
       }
       
-      // For other tables, always add organisation_id
+      // For other tables, add organisation_id if available
+      // Super-admins might not have organisationId set, so allow them to set it explicitly
+      if (this.isSuperAdmin && !this.organisationId) {
+        // Super admin without organisationId: Don't force it (can be set explicitly if needed)
+        return originalInsert(values);
+      }
+      
+      // Non-super-admin or super-admin with organisationId: Add organisation_id
+      // organisationId should always be available for non-super-admins (validateContext ensures this)
+      if (!this.organisationId) {
+        throw new OrganisationContextRequiredError();
+      }
       const contextValues = Array.isArray(values) 
         ? values.map(v => ({ ...v, organisation_id: this.organisationId }))
         : { ...values, organisation_id: this.organisationId };
@@ -213,6 +274,10 @@ export class SecureSupabaseClient {
    * - Super admins: No org filter (see all users) - RLS will allow access
    * - Non-super-admins: Apply org filter as defense in depth - RLS will also filter
    * 
+   * For system-wide tables (like core_organisations):
+   * - Super admins: No org filter (see all records) - RLS will allow access
+   * - Non-super-admins: Apply org filter as defense in depth - RLS will also filter
+   * 
    * For other tables:
    * - Always apply org filter unless super admin bypasses it
    */
@@ -223,6 +288,18 @@ export class SecureSupabaseClient {
       'rbac_apps', // App configuration table - no organisation scope
       'rbac_app_pages', // Page configuration table - scoped by app_id, not organisation_id
       'rbac_global_roles', // Global roles - no organisation scope
+      // Person-scoped tables (organisation_id was removed in person-scoped profiles migration)
+      'core_person', // Person records - person-scoped, no organisation_id
+      'core_member', // Member profiles - person-scoped, no organisation_id
+      'core_contact', // Contact profiles - person-scoped, no organisation_id
+      'core_consent', // Consent records - person-scoped, no organisation_id
+      'core_identification', // Identification records - person-scoped, no organisation_id
+      'core_qualification', // Qualification records - person-scoped, no organisation_id
+      'medi_profile', // Medical profiles - person-scoped, no organisation_id
+      'medi_condition', // Medical conditions - person-scoped via medi_profile, no organisation_id
+      'medi_diet', // Medical diets - person-scoped via medi_profile, no organisation_id
+      'medi_action_plan', // Medical action plans - person-scoped via medi_profile, no organisation_id
+      'medi_profile_versions', // Medical profile versions - person-scoped via medi_profile, no organisation_id
     ];
     
     // Skip organisation filter for tables that don't have organisation_id column
@@ -235,6 +312,17 @@ export class SecureSupabaseClient {
       return query;
     }
     
+    // System-wide tables that super-admins should be able to query without organisation filters
+    // These tables have organisation_id but super-admins need to see all records
+    const systemWideTablesForSuperAdmins = [
+      'core_organisations', // Super-admins need to see all organisations
+    ];
+    
+    // For system-wide tables, super-admins bypass organisation filter
+    if (systemWideTablesForSuperAdmins.includes(tableName) && this.isSuperAdmin) {
+      return query; // No filter - RLS handles access control
+    }
+    
     // For rbac_user_profiles, use conditional filtering based on super admin status
     if (tableName === 'rbac_user_profiles') {
       // Super admins: No org filter (see all users via RLS)
@@ -261,17 +349,69 @@ export class SecureSupabaseClient {
 
   /**
    * Validate that required context is present
+   * Super-admins can operate without organisation context
    */
   private validateContext() {
+    // Super-admins can operate without organisation context
+    if (this.isSuperAdmin) {
+      return;
+    }
+    
     if (!this.organisationId) {
       throw new OrganisationContextRequiredError();
     }
   }
 
+  /**
+   * Determine whether a table requires organisation context.
+   * Tables without an organisation_id column (or global configuration tables) are safe without org context.
+   */
+  private tableRequiresOrganisationContext(tableName: string): boolean {
+    // Keep this list aligned with the tables handled in `addOrganisationFilter` / `injectContext`.
+    const tablesWithoutOrganisationId = new Set<string>([
+      'core_organisations',
+      'rbac_apps',
+      'rbac_app_pages',
+      'rbac_global_roles',
+      'core_person',
+      'core_member',
+      'core_contact',
+      'core_consent',
+      'core_identification',
+      'core_qualification',
+      'medi_profile',
+      'medi_condition',
+      'medi_diet',
+      'medi_action_plan',
+      'medi_profile_versions',
+    ]);
+
+    return !tablesWithoutOrganisationId.has(tableName);
+  }
+
+  /**
+   * Validate context for a specific table operation.
+   */
+  private validateContextForTable(tableName: string) {
+    if (this.isSuperAdmin) return;
+    if (!this.organisationId && this.tableRequiresOrganisationContext(tableName)) {
+      throw new OrganisationContextRequiredError();
+    }
+  }
+
+  /**
+   * Validate context for a specific RPC call.
+   */
+  private validateContextForRpc(fn: string) {
+    if (this.isSuperAdmin) return;
+    if (SecureSupabaseClient.GLOBAL_RPC_ALLOWLIST.has(fn)) return;
+    this.validateContext();
+  }
+
   /**
    * Get the current organisation ID
    */
-  getOrganisationId(): UUID {
+  getOrganisationId(): UUID | null {
     return this.organisationId;
   }
 
@@ -293,7 +433,7 @@ export class SecureSupabaseClient {
    * Create a new client with updated context
    */
   withContext(updates: {
-    organisationId?: UUID;
+    organisationId?: UUID | null;
     eventId?: string;
     appId?: UUID;
     isSuperAdmin?: boolean;
@@ -301,7 +441,7 @@ export class SecureSupabaseClient {
     return new SecureSupabaseClient(
       this.supabaseUrl,
       this.supabaseKey,
-      updates.organisationId || this.organisationId,
+      updates.organisationId !== undefined ? updates.organisationId : this.organisationId,
       updates.eventId !== undefined ? updates.eventId : this.eventId,
       updates.appId !== undefined ? updates.appId : this.appId,
       updates.isSuperAdmin !== undefined ? updates.isSuperAdmin : this.isSuperAdmin
@@ -329,33 +469,43 @@ export class SecureSupabaseClient {
   }
 }
 
-/**
- * Create a secure Supabase client with organisation context
- * 
- * @param supabaseUrl - Supabase project URL
- * @param supabaseKey - Supabase publishable key or anon key (accepts both legacy anon keys and modern publishable keys)
- * @param organisationId - Required organisation ID
- * @param eventId - Optional event ID
- * @param appId - Optional app ID
- * @param isSuperAdmin - Optional super admin flag (defaults to false)
- * @returns SecureSupabaseClient instance
- * 
- * @example
- * ```typescript
- * const client = createSecureClient(
- *   'https://your-project.supabase.co',
- *   'your-publishable-key-or-anon-key',
- *   'org-123',
- *   'event-456',
- *   'app-789',
- *   false // isSuperAdmin
- * );
- * ```
- */
+  /**
+   * Create a secure Supabase client with organisation context
+   * 
+   * @param supabaseUrl - Supabase project URL
+   * @param supabaseKey - Supabase publishable key or anon key (accepts both legacy anon keys and modern publishable keys)
+   * @param organisationId - Organisation ID (optional for super-admins)
+   * @param eventId - Optional event ID
+   * @param appId - Optional app ID
+   * @param isSuperAdmin - Optional super admin flag (defaults to false). When true, organisationId can be null.
+   * @returns SecureSupabaseClient instance
+   * 
+   * @example
+   * ```typescript
+   * const client = createSecureClient(
+   *   'https://your-project.supabase.co',
+   *   'your-publishable-key-or-anon-key',
+   *   'org-123',
+   *   'event-456',
+   *   'app-789',
+   *   false // isSuperAdmin
+   * );
+   * 
+   * // For super-admins, organisationId can be null
+   * const superAdminClient = createSecureClient(
+   *   'https://your-project.supabase.co',
+   *   'your-publishable-key-or-anon-key',
+   *   null, // organisationId not required for super-admins
+   *   undefined,
+   *   undefined,
+   *   true // isSuperAdmin
+   * );
+   * ```
+   */
 export function createSecureClient(
   supabaseUrl: string,
   supabaseKey: string,
-  organisationId: UUID,
+  organisationId: UUID | null,
   eventId?: string,
   appId?: UUID,
   isSuperAdmin: boolean = false
@@ -374,11 +524,12 @@ export function createSecureClient(
  */
 export function fromSupabaseClient(
   client: SupabaseClient<Database>,
-  organisationId: UUID,
+  organisationId: UUID | null,
   eventId?: string,
-  appId?: UUID
+  appId?: UUID,
+  isSuperAdmin: boolean = false
 ): SecureSupabaseClient {
-  // We need the URL and key to create a new client, but they're not accessible
-  // This function should be used with createSecureClient instead
-  throw new Error('fromSupabaseClient is not supported. Use createSecureClient instead.');
+  // Wrap the existing client to reuse auth/session while enforcing organisation/event/app context.
+  // URL/key are unused in this mode.
+  return new SecureSupabaseClient('', '', organisationId, eventId, appId, isSuperAdmin, client);
 }

package/src/rbac/types.ts

@@ -28,12 +28,20 @@ export type AccessLevel =
   | 'admin'
   | 'super';
 
+/**
+ * Scope defines the context for permission checks.
+ * Can include organisation, event, and/or app identifiers.
+ */
 export type Scope = {
   organisationId?: UUID;
   eventId?: string; // event_id is text/varchar
   appId?: AppId | UUID;
 };
 
+/**
+ * Permission check request parameters.
+ * Defines who (userId) is checking what permission in what context (scope).
+ */
 export type PermissionCheck = {
   userId: UUID;
   scope: Scope;

package/src/theming/__tests__/parseEventColours.test.ts

@@ -87,8 +87,8 @@ describe('parseAndNormalizeEventColours', () => {
     });
   });
 
-  describe('Legacy format (ev-main/ev-sec/ev-acc keys)', () => {
-    it('parses legacy format with ev-main, ev-sec, ev-acc keys', () => {
+  describe('Standard format only', () => {
+    it('returns null for legacy format with ev-main, ev-sec, ev-acc keys', () => {
       const input = {
         'ev-main': { 500: { L: 0.5, C: 0.2, H: 0 } },
         'ev-sec': { 500: { L: 0.5, C: 0.2, H: 120 } },
@@ -96,13 +96,11 @@ describe('parseAndNormalizeEventColours', () => {
       };
 
       const result = parseAndNormalizeEventColours(input);
-      expect(result).not.toBeNull();
-      expect(result?.main).toBeDefined();
-      expect(result?.sec).toBeDefined();
-      expect(result?.acc).toBeDefined();
+      // Legacy format is no longer supported - returns null
+      expect(result).toBeNull();
     });
 
-    it('prefers standard keys over legacy keys when both exist', () => {
+    it('uses standard keys when provided', () => {
       const input = {
         main: { 500: { L: 0.5, C: 0.2, H: 0 } },
         'ev-main': { 500: { L: 0.7, C: 0.3, H: 10 } }
@@ -110,8 +108,7 @@ describe('parseAndNormalizeEventColours', () => {
 
       const result = parseAndNormalizeEventColours(input);
       expect(result).not.toBeNull();
-      // Implementation prefers standard keys ('main') over legacy keys ('ev-main')
-      // So when both exist, 'main' is used
+      // Only standard keys are used - legacy keys are ignored
       expect(result?.main[500]).toEqual({ L: 0.5, C: 0.2, H: 0 });
     });
   });

package/src/theming/parseEventColours.ts

@@ -15,9 +15,8 @@ const log = createLogger('ParseEventColours');
 /**
  * Parse and normalize event_colours to PaletteData
  * 
- * Supports multiple input formats:
+ * Supports input formats:
  * - Object with 'main', 'sec', 'acc' keys
- * - Object with 'ev-main', 'ev-sec', 'ev-acc' keys (legacy)
  * - JSON string that will be parsed
  * 
  * Only includes explicitly defined color values. Does not fill
@@ -39,17 +38,6 @@ const log = createLogger('ParseEventColours');
  * // Returns: { main: { 500: {...}, raw: {...} }, sec: { 500: {...} }, acc: { 500: {...} } }
  * ```
  * 
- * @example
- * ```ts
- * // Legacy format with ev-* keys
- * const colours = {
- *   "ev-main": { 500: { L: 0.5, C: 0.2, H: 0 } },
- *   "ev-sec": { 500: { L: 0.5, C: 0.2, H: 120 } },
- *   "ev-acc": { 500: { L: 0.5, C: 0.2, H: 240 } }
- * };
- * const palette = parseAndNormalizeEventColours(colours);
- * // Returns normalized palette with only defined shades included
- * ```
  */
 export function parseAndNormalizeEventColours(input: unknown): { main: any; sec: any; acc: any } | null {
   try {
@@ -67,12 +55,10 @@ export function parseAndNormalizeEventColours(input: unknown): { main: any; sec:
       return null;
     }
 
-    // Support both 'ev-main'/'ev-sec'/'ev-acc' (legacy) and 'main'/'sec'/'acc' (standard) keys
-    // Prefer standard keys over legacy keys when both exist
-    const pick = (o: any, standard: string, legacy: string) => (o?.[standard] ?? o?.[legacy]) || null;
-    const main = pick(obj, 'main', 'ev-main');
-    const sec  = pick(obj, 'sec',  'ev-sec');
-    const acc  = pick(obj, 'acc',  'ev-acc');
+    // Use standard 'main'/'sec'/'acc' keys
+    const main = obj?.main || null;
+    const sec  = obj?.sec  || null;
+    const acc  = obj?.acc  || null;
     
     // If no palette data found, return null
     if (!main && !sec && !acc) return null;

package/src/types/vitest-globals.d.ts

@@ -1,33 +1,58 @@
 
 /// <reference types="vitest/globals" />
+/// <reference types="@testing-library/jest-dom" />
 
-import * as matchers from '@testing-library/jest-dom/matchers';
-
-// Type definitions for @testing-library/jest-dom
-interface CustomMatchers<R = unknown> {
-  toBeInTheDocument(): R;
-  toBeVisible(): R;
-  toBeDisabled(): R;
-  toHaveAttribute(attr: string, value?: string): R;
-  toHaveClass(...classNames: string[]): R;
-  toHaveValue(value: string | string[] | number): R;
-  toHaveTextContent(text: string | RegExp, options?: { normalizeWhitespace: boolean }): R;
-  toBeChecked(): R;
-  toBeEmpty(): R;
-  toBeInvalid(): R;
-  toBeRequired(): R;
-  toBeValid(): R;
-  toContainElement(element: HTMLElement | null): R;
-  toContainHTML(htmlText: string): R;
-  toHaveFocus(): R;
-  toHaveFormValues(expectedValues: Record<string, unknown>): R;
-  toHaveStyle(css: string | Record<string, unknown>): R;
-  toBeEnabled(): R;
-}
-
+// Type definitions for @testing-library/jest-dom matchers
+// These extend Vitest's Assertion interface with jest-dom matchers
 declare module 'vitest' {
-  interface Assertion<T = unknown> extends CustomMatchers<T> {}
-  interface AsymmetricMatchersContaining extends CustomMatchers {}
+  interface Assertion<T = unknown> {
+    // DOM matchers
+    toBeInTheDocument(): void;
+    toBeVisible(): void;
+    toBeDisabled(): void;
+    toBeEnabled(): void;
+    toBeEmpty(): void;
+    toBeEmptyDOMElement(): void;
+    toBeInvalid(): void;
+    toBeValid(): void;
+    toBeRequired(): void;
+    toBeChecked(): void;
+    toHaveFocus(): void;
+    
+    // Attribute and class matchers
+    toHaveAttribute(attr: string, value?: string): void;
+    toHaveClass(...classNames: string[]): void;
+    toHaveStyle(css: string | Record<string, unknown>): void;
+    
+    // Content matchers
+    toHaveTextContent(text: string | RegExp, options?: { normalizeWhitespace?: boolean }): void;
+    toHaveValue(value: string | string[] | number): void;
+    toContainElement(element: HTMLElement | null): void;
+    toContainHTML(htmlText: string): void;
+    toHaveFormValues(expectedValues: Record<string, unknown>): void;
+  }
+  
+  interface AsymmetricMatchersContaining {
+    toBeInTheDocument(): void;
+    toBeVisible(): void;
+    toBeDisabled(): void;
+    toBeEnabled(): void;
+    toBeEmpty(): void;
+    toBeEmptyDOMElement(): void;
+    toBeInvalid(): void;
+    toBeValid(): void;
+    toBeRequired(): void;
+    toBeChecked(): void;
+    toHaveFocus(): void;
+    toHaveAttribute(attr: string, value?: string): void;
+    toHaveClass(...classNames: string[]): void;
+    toHaveStyle(css: string | Record<string, unknown>): void;
+    toHaveTextContent(text: string | RegExp, options?: { normalizeWhitespace?: boolean }): void;
+    toHaveValue(value: string | string[] | number): void;
+    toContainElement(element: HTMLElement | null): void;
+    toContainHTML(htmlText: string): void;
+    toHaveFormValues(expectedValues: Record<string, unknown>): void;
+  }
 }
 
 // Ensure vitest globals are available

package/src/utils/__mocks__/supabaseMock.ts

@@ -1,10 +1,8 @@
-
+/// <reference types="vitest/globals" />
 /**
  * @file Supabase mock for testing
  */
 
-import { vi } from 'vitest';
-
 export function createMockSupabaseClient(overrides: Record<string, unknown> = {}) {
   const mockOrder = vi.fn().mockResolvedValue({ 
     data: [

package/src/utils/__tests__/formatting.unit.test.ts

@@ -35,7 +35,7 @@ describe('formatting utilities', () => {
       expect(formatPercent(0.5)).toBe('0.5%');
     });
     it('formats as percent with custom decimals', () => {
-      expect(formatPercent(0.25, 'en-US', 2)).toBe('0.25%');
+      expect(formatPercent(0.25, 'en-US', { decimals: 2 })).toBe('0.25%');
     });
     
     // Tests for preserveDecimals functionality
@@ -65,9 +65,9 @@ describe('formatting utilities', () => {
         expect(formatPercent(0.81, 'en-US', { decimals: 3, preserveDecimals: false })).toBe('0.810%');
       });
       
-      it('maintains backward compatibility with number parameter', () => {
-        expect(formatPercent(0.81, 'en-US', 1)).toBe('0.8%');
-        expect(formatPercent(0.25, 'en-US', 2)).toBe('0.25%');
+      it('works with explicit decimals option', () => {
+        expect(formatPercent(0.81, 'en-US', { decimals: 1 })).toBe('0.8%');
+        expect(formatPercent(0.25, 'en-US', { decimals: 2 })).toBe('0.25%');
       });
     });
   });

package/src/utils/__tests__/index.unit.test.ts

@@ -137,7 +137,7 @@ describe('utils index exports', () => {
 
   describe('Audit utilities', () => {
     it('should export audit functions', () => {
-      expect(Utils).toHaveProperty('auditLog');
+      expect(Utils).toHaveProperty('auditLogger');
       expect(Utils).toHaveProperty('logAuditEvent');
     });
   });
@@ -237,7 +237,7 @@ describe('utils index exports', () => {
         'pickSchema', // Schema utilities
         'securityMonitor', // Security monitoring
         'useSessionTracking', // Session tracking
-        'auditLog', // Audit
+        'auditLogger', // Audit
         'generateDeviceFingerprint', // Device fingerprinting
         'formatDate', // Formatting
         'setOrganisationContext' // Organisation context

package/src/utils/audit/audit.ts

@@ -84,9 +84,6 @@ class AuditLogger {
 
 export const auditLogger = new AuditLogger();
 
-// Alias for backward compatibility
-export const auditLog = auditLogger;
-
 export function logAuthEvent(action: string, user?: string, details?: Record<string, unknown>): void {
   auditLogger.log({
     type: 'auth',