@makolabs/ripple 1.2.4 → 1.2.8

package/dist/elements/pagination/Pagination.svelte

@@ -324,7 +324,7 @@
 				{#if template === 'full' && showPageNumbers}
 					{#if totalPages <= maxVisiblePages}
 						<!-- Show all pages if total is less than or equal to maxVisiblePages -->
-						{#each Array(totalPages) as page, i (page + i)}
+						{#each Array(totalPages) as page, i (page + '-' + i)}
 							{@const pageNum = i + 1}
 							<button
 								onclick={() => goToPage(pageNum)}

package/dist/user-management/UserManagement.svelte

@@ -1,29 +1,31 @@
 <script lang="ts">
+	import { onMount } from 'svelte';
 	import { PageHeader, MetricCard, Button, cn } from '../index.js';
 	import UserTable from './UserTable.svelte';
 	import UserModal from './UserModal.svelte';
 	import UserViewModal from './UserViewModal.svelte';
-	import type { User, UserManagementProps } from './user-management.js';
+	import type { User, UserManagementProps, Role, Permission } from './user-management.js';
 	import { SvelteSet } from 'svelte/reactivity';
+	import * as UserManagementAdapter from './adapters/UserManagement.remote.js';
 
 	let {
-		users = [],
-		totalUsers = 0,
-		loading = false,
-		currentPage = 1,
-		pageSize = 10,
-		roles = [],
-		permissions = [],
-		onPageChange,
-		onPageSizeChange,
-		onSort,
-		onCreateUser,
-		onUpdateUser,
-		onDeleteUser,
-		onDeleteUsers,
+		adapter = UserManagementAdapter,
+		roles: initialRoles = [],
+		permissions: initialPermissions = [],
 		class: className
 	}: UserManagementProps = $props();
 
+	// Internal state
+	let users = $state<User[]>([]);
+	let totalUsers = $state(0);
+	let loading = $state(false);
+	let currentPage = $state(1);
+	let pageSize = $state(10);
+	let sortBy = $state<string | null>(null);
+	let sortOrder = $state<'asc' | 'desc'>('desc');
+	let roles = $state<Role[]>(initialRoles);
+	let permissions = $state<Permission[]>(initialPermissions);
+
 	// Modal states
 	let showEditCreateModal = $state(false);
 	let showViewModal = $state(false);
@@ -37,6 +39,45 @@
 	const hasSelectedUsers = $derived(selectedUsers.size > 0);
 	const activeUsers = $derived(users.filter((u) => !!u.id));
 
+	// Load users from adapter (remote function)
+	async function loadUsers() {
+		try {
+			loading = true;
+			const result = await adapter.getUsers({
+				page: currentPage,
+				pageSize,
+				sortBy: sortBy || undefined,
+				sortOrder: sortOrder || 'desc'
+			});
+			users = result.users;
+			totalUsers = result.totalUsers;
+		} catch (error) {
+			console.error('Error loading users:', error);
+		} finally {
+			loading = false;
+		}
+	}
+
+	// Handlers
+	async function handlePageChange(page: number) {
+		currentPage = page;
+		await loadUsers();
+	}
+
+	async function handlePageSizeChange(size: number) {
+		pageSize = size;
+		currentPage = 1; // Reset to first page when changing page size
+		await loadUsers();
+	}
+
+	async function handleSort(state: { column: string | null; direction: 'asc' | 'desc' | null }) {
+		if (state.column && state.direction) {
+			sortBy = state.column;
+			sortOrder = state.direction;
+			await loadUsers();
+		}
+	}
+
 	// Modal handlers
 	function openViewModal(user: User) {
 		selectedUser = user;
@@ -62,10 +103,16 @@
 
 	// Save handlers
 	async function handleUserSave(user: User, mode: 'create' | 'edit') {
-		if (mode === 'create' && onCreateUser) {
-			await onCreateUser(user);
-		} else if (mode === 'edit' && onUpdateUser) {
-			await onUpdateUser(user.id, user);
+		try {
+			if (mode === 'create') {
+				await adapter.createUser(user);
+			} else {
+				await adapter.updateUser({ userId: user.id, userData: user });
+			}
+			await loadUsers();
+		} catch (error) {
+			console.error('Error saving user:', error);
+			throw error;
 		}
 	}
 
@@ -74,8 +121,12 @@
 		if (!confirm('Are you sure you want to delete this user? This action cannot be undone.')) {
 			return;
 		}
-		if (onDeleteUser) {
-			await onDeleteUser(userId);
+		try {
+			await adapter.deleteUser(userId);
+			await loadUsers();
+		} catch (error) {
+			console.error('Error deleting user:', error);
+			throw error;
 		}
 	}
 
@@ -89,13 +140,23 @@
 			return;
 		}
 
-		if (bulkAction === 'delete' && onDeleteUsers) {
-			await onDeleteUsers(userIds);
-			selectedUsers.clear();
-			selectedUsers = new SvelteSet(selectedUsers);
-			bulkAction = '';
+		if (bulkAction === 'delete') {
+			try {
+				await adapter.deleteUsers(userIds);
+				selectedUsers.clear();
+				bulkAction = '';
+				await loadUsers();
+			} catch (error) {
+				console.error('Error deleting users:', error);
+				throw error;
+			}
 		}
 	}
+
+	// Initialize on mount
+	onMount(async () => {
+		await loadUsers();
+	});
 </script>
 
 {#snippet PlusIcon()}
@@ -112,7 +173,7 @@
 		layout="horizontal"
 		class="mb-6"
 	>
-		<Button onclick={openCreateModal} color="primary" disabled={!onCreateUser}>
+		<Button onclick={openCreateModal} color="primary">
 			{@render PlusIcon()}
 			Add User
 		</Button>
@@ -156,9 +217,9 @@
 		{currentPage}
 		{pageSize}
 		{totalUsers}
-		{onPageChange}
-		{onPageSizeChange}
-		{onSort}
+		onPageChange={handlePageChange}
+		onPageSizeChange={handlePageSizeChange}
+		onSort={handleSort}
 		onView={openViewModal}
 		onEdit={openEditModal}
 		onDelete={handleDeleteUser}

package/dist/user-management/UserManagementTestWrapper.svelte

@@ -1,47 +1,33 @@
 <script lang="ts">
+	import { onMount } from 'svelte';
 	import UserManagement from './UserManagement.svelte';
 	import type { UserManagementProps } from './user-management.js';
+	import * as mockAdapter from './adapters/mockUserManagement.js';
+	import { resetState } from './adapters/mockUserManagement.js';
+	import type { User, Role, Permission } from './user-management.js';
 
-	interface Props extends UserManagementProps {
+	interface Props extends Omit<UserManagementProps, 'adapter'> {
 		testId?: string;
+		initialUsers?: User[];
+		roles?: Role[];
+		permissions?: Permission[];
+		simulateDelay?: boolean;
+		delayMs?: number;
 	}
 
-	let {
-		users = [],
-		totalUsers = 0,
-		loading = false,
-		currentPage = 1,
-		pageSize = 10,
-		roles = [],
-		permissions = [],
-		onPageChange = () => {},
-		onPageSizeChange = () => {},
-		onSort,
-		onCreateUser,
-		onUpdateUser,
-		onDeleteUser,
-		onDeleteUsers,
-		testId,
-		...rest
-	}: Props = $props();
+	let { testId, initialUsers, roles, permissions, simulateDelay, delayMs, ...rest }: Props =
+		$props();
+
+	// Initialize mock adapter with provided data
+	onMount(async () => {
+		await resetState({
+			initialUsers,
+			simulateDelay,
+			delayMs
+		});
+	});
 </script>
 
 <div data-testid={testId}>
-	<UserManagement
-		{users}
-		{totalUsers}
-		{loading}
-		{currentPage}
-		{pageSize}
-		{roles}
-		{permissions}
-		{onPageChange}
-		{onPageSizeChange}
-		{onSort}
-		{onCreateUser}
-		{onUpdateUser}
-		{onDeleteUser}
-		{onDeleteUsers}
-		{...rest}
-	/>
+	<UserManagement adapter={mockAdapter} {roles} {permissions} {...rest} />
 </div>

package/dist/user-management/UserManagementTestWrapper.svelte.d.ts

@@ -1,6 +1,12 @@
 import type { UserManagementProps } from './user-management.js';
-interface Props extends UserManagementProps {
+import type { User, Role, Permission } from './user-management.js';
+interface Props extends Omit<UserManagementProps, 'adapter'> {
     testId?: string;
+    initialUsers?: User[];
+    roles?: Role[];
+    permissions?: Permission[];
+    simulateDelay?: boolean;
+    delayMs?: number;
 }
 declare const UserManagementTestWrapper: import("svelte").Component<Props, {}, "">;
 type UserManagementTestWrapper = ReturnType<typeof UserManagementTestWrapper>;

package/dist/user-management/UserModal.svelte

@@ -25,7 +25,6 @@
 	let formData = $state<Partial<User>>({
 		first_name: '',
 		last_name: '',
-		username: '',
 		email_addresses: [{ email_address: '' }],
 		phone_numbers: [],
 		role: '',
@@ -38,7 +37,6 @@
 			formData = {
 				first_name: user.first_name || '',
 				last_name: user.last_name || '',
-				username: user.username || '',
 				email_addresses: user.email_addresses || [{ email_address: '' }],
 				phone_numbers: user.phone_numbers || [],
 				role: user.role || '',
@@ -49,7 +47,6 @@
 			formData = {
 				first_name: '',
 				last_name: '',
-				username: '',
 				email_addresses: [{ email_address: '' }],
 				phone_numbers: [],
 				role: '',
@@ -91,7 +88,6 @@
 				id: user?.id || '',
 				first_name: formData.first_name,
 				last_name: formData.last_name,
-				username: formData.username,
 				email_addresses: formData.email_addresses,
 				phone_numbers: formData.phone_numbers,
 				role: formData.role,
@@ -194,20 +190,6 @@
 					<p class="mt-1 text-xs text-red-500">{formErrors.email}</p>
 				{/if}
 			</div>
-
-			<!-- Username (Optional) -->
-			<div>
-				<label for="username" class="mb-1 block text-sm font-medium text-gray-700">
-					Username
-				</label>
-				<input
-					id="username"
-					type="text"
-					bind:value={formData.username}
-					class="w-full rounded-lg border border-gray-300 px-3 py-2 focus:border-blue-500 focus:ring-2 focus:ring-blue-500"
-					placeholder="username"
-				/>
-			</div>
 		</div>
 
 		<!-- Right Column: Permissions & Role -->

package/dist/user-management/UserViewModal.svelte

@@ -127,12 +127,6 @@
 										{getUserDisplayName(user)}
 									</p>
 								</div>
-								{#if user?.username}
-									<div>
-										<span class="text-xs text-gray-500">Username</span>
-										<p class="text-sm">{user.username}</p>
-									</div>
-								{/if}
 								<div>
 									<span class="text-xs text-gray-500">User ID</span>
 									<p class="font-mono text-xs break-all">{user?.id || 'N/A'}</p>

package/dist/user-management/adapters/UserManagement.remote.d.ts

@@ -0,0 +1,68 @@
+/**
+ * User Management Remote Functions
+ *
+ * Complete implementation template for user management remote functions.
+ * This follows the same pattern as users.remote.ts and is designed to be
+ * used as-is in SvelteKit applications like sharkfin-frontend.
+ *
+ * Configuration:
+ * - Set environment variables: CLERK_SECRET_KEY, ADMIN_API_KEY, PRIVATE_BASE_AUTH_URL, ALLOWED_ORG_ID
+ * - Configure CLIENT_ID via ADMIN_CONFIG or env variable (CLIENT_ID)
+ * - Adjust permission prefix filter via PERMISSION_PREFIX env variable
+ *
+ * @see https://svelte.dev/docs/kit/remote-functions
+ *
+ * Usage in your app:
+ * ```svelte
+ * <script>
+ *   import { UserManagement } from '@makolabs/ripple';
+ *   import * as adapter from '../UserManagement.remote';
+ * </script>
+ *
+ * <UserManagement adapter={adapter} />
+ * ```
+ */
+import type { User } from '../user-management.js';
+import type { GetUsersOptions, GetUsersResult } from './types.js';
+/**
+ * Get users with pagination and sorting
+ *
+ * Transforms adapter options to Clerk API format
+ */
+export declare const getUsers: import("@sveltejs/kit").RemoteQueryFunction<GetUsersOptions, GetUsersResult>;
+/**
+ * Create a new user
+ *
+ * Creates user in Clerk, optionally adds to organization, and creates admin key with permissions
+ */
+export declare const createUser: import("@sveltejs/kit").RemoteCommand<Partial<User>, Promise<User>>;
+/**
+ * Update an existing user
+ */
+export declare const updateUser: import("@sveltejs/kit").RemoteCommand<{
+    userId: string;
+    userData: Partial<User>;
+}, Promise<User>>;
+/**
+ * Delete a single user
+ */
+export declare const deleteUser: import("@sveltejs/kit").RemoteCommand<string, Promise<void>>;
+/**
+ * Delete multiple users
+ */
+export declare const deleteUsers: import("@sveltejs/kit").RemoteCommand<string[], Promise<void>>;
+/**
+ * Get permissions for a specific user
+ *
+ * Uses 'sub' (userId) parameter in admin API calls
+ */
+export declare const getUserPermissions: import("@sveltejs/kit").RemoteQueryFunction<string, string[]>;
+/**
+ * Update permissions for a specific user
+ *
+ * Uses 'sub' (userId) parameter in admin API calls
+ */
+export declare const updateUserPermissions: import("@sveltejs/kit").RemoteCommand<{
+    userId: string;
+    permissions: string[];
+}, Promise<void>>;

package/dist/user-management/adapters/UserManagement.remote.js

@@ -0,0 +1,487 @@
+/**
+ * User Management Remote Functions
+ *
+ * Complete implementation template for user management remote functions.
+ * This follows the same pattern as users.remote.ts and is designed to be
+ * used as-is in SvelteKit applications like sharkfin-frontend.
+ *
+ * Configuration:
+ * - Set environment variables: CLERK_SECRET_KEY, ADMIN_API_KEY, PRIVATE_BASE_AUTH_URL, ALLOWED_ORG_ID
+ * - Configure CLIENT_ID via ADMIN_CONFIG or env variable (CLIENT_ID)
+ * - Adjust permission prefix filter via PERMISSION_PREFIX env variable
+ *
+ * @see https://svelte.dev/docs/kit/remote-functions
+ *
+ * Usage in your app:
+ * ```svelte
+ * <script>
+ *   import { UserManagement } from '@makolabs/ripple';
+ *   import * as adapter from '../UserManagement.remote';
+ * </script>
+ *
+ * <UserManagement adapter={adapter} />
+ * ```
+ */
+import { query, command } from '$app/server';
+import { env } from '$env/dynamic/private';
+/**
+ * Configuration
+ * Override these values or import from your config file
+ */
+// Option 1: Import from your config (recommended)
+// import { ADMIN_CONFIG } from '../../constants/permissions';
+// const CLIENT_ID = ADMIN_CONFIG.CLIENT_ID;
+// Option 2: Use environment variable
+const CLIENT_ID = env.CLIENT_ID || 'sharkfin'; // Default fallback
+// Permission prefix filter - adjust based on your permission structure
+// Example: 'sharkfin:' filters to only sharkfin permissions
+const PERMISSION_PREFIX = env.PERMISSION_PREFIX || 'sharkfin:';
+// Organization ID for adding users to organizations
+const ORGANIZATION_ID = env.ALLOWED_ORG_ID;
+/**
+ * Helper: Make authenticated request to Clerk API
+ */
+async function makeClerkRequest(endpoint, options = {}) {
+    const CLERK_SECRET_KEY = env.CLERK_SECRET_KEY;
+    if (!CLERK_SECRET_KEY) {
+        throw new Error('CLERK_SECRET_KEY environment variable is required');
+    }
+    const response = await fetch(`https://api.clerk.com/v1${endpoint}`, {
+        ...options,
+        headers: {
+            Authorization: `Bearer ${CLERK_SECRET_KEY}`,
+            'Content-Type': 'application/json',
+            ...options.headers
+        }
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        console.error(`❌ [Clerk API] ${response.status} ${response.statusText} - ${errorText}`);
+        // Try to parse error details
+        let errorDetails;
+        try {
+            errorDetails = JSON.parse(errorText);
+        }
+        catch {
+            errorDetails = { message: errorText || `${response.status} ${response.statusText}` };
+        }
+        // Throw error with status and details for better frontend handling
+        const error = new Error(errorDetails.message || `Clerk API request failed: ${response.status} ${response.statusText}`);
+        error.status = response.status;
+        error.details = errorDetails;
+        throw error;
+    }
+    return response.json();
+}
+/**
+ * Helper: Make authenticated request to Admin API
+ */
+async function makeAdminRequest(endpoint, options = {}) {
+    const ADMIN_API_KEY = env.ADMIN_API_KEY;
+    const PRIVATE_BASE_AUTH_URL = env.PRIVATE_BASE_AUTH_URL;
+    if (!ADMIN_API_KEY || !PRIVATE_BASE_AUTH_URL) {
+        const missing = [];
+        if (!ADMIN_API_KEY)
+            missing.push('ADMIN_API_KEY');
+        if (!PRIVATE_BASE_AUTH_URL)
+            missing.push('PRIVATE_BASE_AUTH_URL');
+        throw new Error(`Admin API configuration missing: ${missing.join(', ')}`);
+    }
+    const url = `${PRIVATE_BASE_AUTH_URL}${endpoint}`;
+    const response = await fetch(url, {
+        ...options,
+        headers: {
+            'X-Admin-API-Key': ADMIN_API_KEY,
+            'Content-Type': 'application/json',
+            ...options.headers
+        }
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        console.error(`❌ [Admin API] ${response.status} ${response.statusText} - ${errorText}`);
+        throw new Error(`Admin API request failed: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+    return response.json();
+}
+/**
+ * Helper: Create admin key with permissions for a user
+ *
+ * @param userId - The user ID (used as 'sub' in admin API)
+ * @param permissions - Array of permission strings
+ * @param clientId - Client ID (defaults to CLIENT_ID config)
+ */
+async function createUserPermissions(userId, permissions, clientId = CLIENT_ID) {
+    console.log(`🔑 [createUserPermissions] Creating admin key for user ${userId}`);
+    // Filter permissions by prefix if configured
+    const filteredPermissions = PERMISSION_PREFIX
+        ? permissions.filter((scope) => scope.startsWith(PERMISSION_PREFIX))
+        : permissions;
+    if (filteredPermissions.length === 0) {
+        console.log(`⚠️ [createUserPermissions] No ${PERMISSION_PREFIX || ''} permissions provided, skipping`);
+        return null;
+    }
+    const createData = await makeAdminRequest('/admin/keys', {
+        method: 'POST',
+        body: JSON.stringify({
+            client_id: clientId,
+            sub: userId, // userId is used as 'sub' parameter
+            scopes: filteredPermissions
+        })
+    });
+    console.log(`✅ [createUserPermissions] Admin key created successfully for user ${userId}`);
+    return createData;
+}
+/**
+ * Get users with pagination and sorting
+ *
+ * Transforms adapter options to Clerk API format
+ */
+export const getUsers = query('unchecked', async (options) => {
+    console.log('🔍 [getUsers] Fetching users with options:', options);
+    try {
+        // Transform adapter options to Clerk API format
+        const limit = options.pageSize;
+        const offset = (options.page - 1) * options.pageSize;
+        // Build orderBy string
+        let orderBy = '';
+        if (options.sortBy) {
+            const prefix = options.sortOrder === 'desc' ? '-' : '';
+            orderBy = `${prefix}${options.sortBy}`;
+        }
+        else {
+            orderBy = '-created_at'; // Default
+        }
+        // Build Clerk API parameters
+        const params = new URLSearchParams({
+            limit: limit.toString(),
+            offset: offset.toString(),
+            order_by: orderBy
+        });
+        if (options.query)
+            params.append('query', options.query);
+        // Fetch users and count in parallel
+        const [usersData, countData] = await Promise.all([
+            makeClerkRequest(`/users?${params}`),
+            makeClerkRequest(`/users/count?${params}`)
+        ]);
+        console.log(`✅ [getUsers] Fetched ${usersData.length} users, total: ${countData.total_count}`);
+        return {
+            users: usersData,
+            totalUsers: countData.total_count || 0
+        };
+    }
+    catch (error) {
+        console.error('❌ [getUsers] Error:', error);
+        throw new Error(`Failed to fetch users: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+});
+/**
+ * Create a new user
+ *
+ * Creates user in Clerk, optionally adds to organization, and creates admin key with permissions
+ */
+export const createUser = command('unchecked', async (userData) => {
+    // Transform User to Clerk API format
+    const emailAddress = userData.email_addresses?.[0]?.email_address || '';
+    if (!emailAddress) {
+        throw new Error('Email address is required');
+    }
+    console.log('📝 [createUser] Creating new user:', emailAddress);
+    try {
+        // Extract permissions from userData
+        const { permissions, ...userDataOnly } = userData;
+        // Transform userData to match Clerk Backend API format (snake_case)
+        const clerkUserData = {
+            first_name: userDataOnly.first_name || '',
+            last_name: userDataOnly.last_name || '',
+            email_address: [emailAddress], // Clerk expects an array
+            ...(userDataOnly.username && { username: userDataOnly.username }),
+            ...(userDataOnly.private_metadata && { private_metadata: userDataOnly.private_metadata })
+        };
+        // Step 1: Create user in Clerk
+        console.log('📝 [createUser] Creating user in Clerk...');
+        let result = await makeClerkRequest('/users', {
+            method: 'POST',
+            body: JSON.stringify(clerkUserData)
+        });
+        // Step 1.5: Add user to organization if configured
+        if (ORGANIZATION_ID) {
+            try {
+                console.log(`🏢 [createUser] Adding user ${result.id} to organization ${ORGANIZATION_ID}...`);
+                await makeClerkRequest(`/organizations/${ORGANIZATION_ID}/memberships`, {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        user_id: result.id,
+                        role: 'org:member' // Standard Clerk organization role
+                    })
+                });
+                console.log(`✅ [createUser] User added to organization successfully`);
+            }
+            catch (orgError) {
+                console.error(`❌ [createUser] Failed to add user to organization:`, orgError);
+                // Clean up: delete the user since they can't be added to the org
+                try {
+                    await makeClerkRequest(`/users/${result.id}`, {
+                        method: 'DELETE'
+                    });
+                    console.log(`🗑️ [createUser] User ${result.id} deleted due to org membership failure`);
+                }
+                catch (deleteError) {
+                    console.error(`❌ [createUser] Failed to delete user after org membership failure:`, deleteError);
+                }
+                throw new Error(`Failed to add user to organization. User creation rolled back. Error: ${orgError instanceof Error ? orgError.message : String(orgError)}`);
+            }
+        }
+        else {
+            console.warn('⚠️ [createUser] ALLOWED_ORG_ID not configured, skipping organization membership');
+        }
+        // Step 2: Create admin key with permissions if permissions are provided
+        if (permissions && permissions.length > 0) {
+            try {
+                console.log(`🔑 [createUser] Creating permissions for new user: ${result.id}`);
+                const adminKeyResult = await createUserPermissions(result.id, permissions);
+                // Extract the API key from the admin service response
+                const apiKey = adminKeyResult?.data?.key;
+                if (adminKeyResult && apiKey) {
+                    // Update user's private metadata with the API key
+                    const updatedUser = await makeClerkRequest(`/users/${result.id}`, {
+                        method: 'PATCH',
+                        body: JSON.stringify({
+                            private_metadata: {
+                                ...result.private_metadata,
+                                mako_api_key: apiKey
+                            }
+                        })
+                    });
+                    // Update the result with the updated user data
+                    result = updatedUser;
+                    console.log(`✅ [createUser] API key stored in user's private metadata`);
+                }
+                else {
+                    console.warn(`⚠️ [createUser] No API key found in admin key result`);
+                }
+                // Add permission info to result
+                result.adminKey = adminKeyResult;
+                result.permissionsAssigned = permissions;
+                console.log(`✅ [createUser] User ${result.id} created with permissions successfully`);
+            }
+            catch (permissionError) {
+                console.error(`❌ [createUser] Failed to assign permissions:`, permissionError);
+                // Don't fail the entire operation, but warn
+                result.warning = 'User created but permissions assignment failed';
+                result.permissionError =
+                    permissionError instanceof Error ? permissionError.message : String(permissionError);
+            }
+        }
+        else {
+            console.log(`⚠️ [createUser] User ${result.id} created without permissions`);
+        }
+        return result;
+    }
+    catch (error) {
+        console.error('❌ [createUser] Error:', error);
+        // Handle Clerk API errors with detailed information
+        if (error && typeof error === 'object' && 'status' in error && 'details' in error) {
+            const enrichedError = new Error('message' in error && typeof error.message === 'string' ? error.message : 'Unknown error');
+            enrichedError.status = error.status;
+            enrichedError.details = error.details;
+            enrichedError.clerkError = true;
+            throw enrichedError;
+        }
+        throw new Error(`Failed to create user: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+});
+/**
+ * Update an existing user
+ */
+export const updateUser = command('unchecked', async (options) => {
+    const { userId, userData } = options;
+    console.log(`📝 [updateUser] Updating user ${userId}`);
+    try {
+        // Transform User to Clerk API format
+        // Only include fields that Clerk accepts
+        const updateData = {};
+        if (userData.first_name !== undefined)
+            updateData.first_name = userData.first_name;
+        if (userData.last_name !== undefined)
+            updateData.last_name = userData.last_name;
+        if (userData.username !== undefined && userData.username !== '') {
+            // Only include username if it's not empty (prevents "username already exists" error)
+            updateData.username = userData.username;
+        }
+        if (userData.private_metadata !== undefined) {
+            updateData.private_metadata = userData.private_metadata;
+        }
+        const result = await makeClerkRequest(`/users/${userId}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updateData)
+        });
+        // If permissions changed, update them separately
+        if (userData.permissions !== undefined) {
+            try {
+                await updateUserPermissions({ userId, permissions: userData.permissions });
+            }
+            catch (permError) {
+                console.error(`❌ [updateUser] Failed to update permissions:`, permError);
+                // Don't fail the entire operation
+            }
+        }
+        console.log(`✅ [updateUser] User ${userId} updated successfully`);
+        return result;
+    }
+    catch (error) {
+        console.error('❌ [updateUser] Error:', error);
+        // Handle Clerk API errors with detailed information
+        if (error && typeof error === 'object' && 'status' in error && 'details' in error) {
+            const enrichedError = new Error('message' in error && typeof error.message === 'string' ? error.message : 'Unknown error');
+            enrichedError.status = error.status;
+            enrichedError.details = error.details;
+            enrichedError.clerkError = true;
+            throw enrichedError;
+        }
+        throw new Error(`Failed to update user: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+});
+/**
+ * Delete a single user
+ */
+export const deleteUser = command('unchecked', async (userId) => {
+    console.log(`🗑️ [deleteUser] Deleting user ${userId}`);
+    try {
+        await makeClerkRequest(`/users/${userId}`, {
+            method: 'DELETE'
+        });
+        console.log(`✅ [deleteUser] User ${userId} deleted successfully`);
+    }
+    catch (error) {
+        console.error('❌ [deleteUser] Error:', error);
+        throw new Error(`Failed to delete user: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+});
+/**
+ * Delete multiple users
+ */
+export const deleteUsers = command('unchecked', async (userIds) => {
+    console.log(`🗑️ [deleteUsers] Deleting ${userIds.length} users`);
+    try {
+        await Promise.all(userIds.map((userId) => makeClerkRequest(`/users/${userId}`, {
+            method: 'DELETE'
+        })));
+        console.log(`✅ [deleteUsers] ${userIds.length} users deleted successfully`);
+    }
+    catch (error) {
+        console.error('❌ [deleteUsers] Error:', error);
+        throw new Error(`Failed to delete users: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+});
+/**
+ * Get permissions for a specific user
+ *
+ * Uses 'sub' (userId) parameter in admin API calls
+ */
+export const getUserPermissions = query('unchecked', async (userId) => {
+    console.log(`🔍 [getUserPermissions] Fetching permissions for user: ${userId}`);
+    try {
+        // Try direct lookup first using client_id and sub (userId)
+        try {
+            const userData = await makeAdminRequest(`/admin/keys?client_id=${CLIENT_ID}&sub=${userId}`);
+            console.log(`✅ [getUserPermissions] Direct lookup successful for user ${userId}`);
+            // Filter the response to only include active keys
+            if (userData?.data?.data && Array.isArray(userData.data.data)) {
+                userData.data.data = userData.data.data.filter((key) => key.status === 'active');
+                console.log(`🔍 [getUserPermissions] Filtered to ${userData.data.data.length} active key(s)`);
+            }
+            // Extract scopes from the response
+            if (userData?.data?.data && Array.isArray(userData.data.data)) {
+                return userData.data.data.flatMap((key) => key.scopes || []);
+            }
+            else if (userData?.scopes) {
+                return Array.isArray(userData.scopes) ? userData.scopes : [userData.scopes];
+            }
+            return [];
+        }
+        catch {
+            console.log(`❌ [getUserPermissions] Direct lookup failed, trying search by sub field`);
+            // If direct lookup fails with 404, search all keys by sub field
+            try {
+                const allKeysData = await makeAdminRequest('/admin/keys');
+                console.log(`🔍 [getUserPermissions] Searching through ${allKeysData.data?.data?.length || 0} keys`);
+                // Find the ACTIVE key for this user (ignore revoked keys)
+                // Match by sub (userId) and client_id
+                const userKey = allKeysData.data.data.find((key) => key.sub === userId && key.client_id === CLIENT_ID && key.status === 'active');
+                if (userKey) {
+                    console.log(`✅ [getUserPermissions] Found active user key by sub field`);
+                    return Array.isArray(userKey.scopes) ? userKey.scopes : [userKey.scopes];
+                }
+                else {
+                    console.log(`❌ [getUserPermissions] No user found, returning empty permissions`);
+                    return [];
+                }
+            }
+            catch (searchError) {
+                console.error('❌ [getUserPermissions] Error searching for user by sub:', searchError);
+                throw new Error('Failed to fetch user permissions');
+            }
+        }
+    }
+    catch (error) {
+        console.error('❌ [getUserPermissions] Error:', error);
+        throw new Error(`Failed to fetch user permissions: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+});
+/**
+ * Update permissions for a specific user
+ *
+ * Uses 'sub' (userId) parameter in admin API calls
+ */
+export const updateUserPermissions = command('unchecked', async (options) => {
+    const { userId, permissions } = options;
+    console.log(`🔑 [updateUserPermissions] Updating permissions for user ${userId}`);
+    try {
+        let adminKeyId = userId; // Use userId as default key ID
+        // Try direct update first
+        try {
+            await makeAdminRequest(`/admin/keys/${adminKeyId}`, {
+                method: 'PUT',
+                body: JSON.stringify({ scopes: permissions })
+            });
+            console.log(`✅ [updateUserPermissions] Permissions updated successfully`);
+            return;
+        }
+        catch {
+            // If direct update fails, try to find the correct adminKeyId
+            console.log(`⚠️ [updateUserPermissions] Direct update failed, searching for key ID...`);
+            try {
+                const allKeysData = await makeAdminRequest('/admin/keys');
+                // Find the ACTIVE key for this user (ignore revoked keys)
+                // Match by sub (userId) and client_id
+                const userKey = allKeysData.data.data.find((key) => key.sub === userId && key.client_id === CLIENT_ID && key.status === 'active');
+                if (userKey) {
+                    // Use the found key ID for update
+                    adminKeyId = userKey.id;
+                    await makeAdminRequest(`/admin/keys/${adminKeyId}`, {
+                        method: 'PUT',
+                        body: JSON.stringify({ scopes: permissions })
+                    });
+                    console.log(`✅ [updateUserPermissions] Permissions updated successfully (after search)`);
+                    return;
+                }
+                else {
+                    // User doesn't exist, create new admin key
+                    console.log(`📝 [updateUserPermissions] Creating new admin key...`);
+                    await createUserPermissions(userId, permissions);
+                    console.log(`✅ [updateUserPermissions] New admin key created successfully`);
+                    return;
+                }
+            }
+            catch (searchError) {
+                console.error('❌ [updateUserPermissions] Error during permission update:', searchError);
+                throw new Error('Failed to update permissions');
+            }
+        }
+    }
+    catch (error) {
+        console.error('❌ [updateUserPermissions] Error:', error);
+        throw new Error(`Failed to update user permissions: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+});

package/dist/user-management/adapters/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * User Management Adapters
+ *
+ * Adapters are remote function modules (.remote.ts files) that export
+ * query/command functions.
+ *
+ * @see https://svelte.dev/docs/kit/remote-functions
+ */
+export type { GetUsersOptions, GetUsersResult } from './types.js';
+export * from './mockUserManagement.js';

package/dist/user-management/adapters/index.js

@@ -0,0 +1,12 @@
+/**
+ * User Management Adapters
+ *
+ * Adapters are remote function modules (.remote.ts files) that export
+ * query/command functions.
+ *
+ * @see https://svelte.dev/docs/kit/remote-functions
+ */
+// Export mock adapter functions for testing/storybook
+export * from './mockUserManagement.js';
+// Note: UserManagement.remote.ts is a template file showing how to implement
+// remote functions in your SvelteKit app. It is not exported from this library.

package/dist/user-management/adapters/mockUserManagement.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Mock User Management Functions
+ *
+ * Mock implementation of user management functions for testing and development.
+ * These are regular async functions that match the UserManagementAdapter interface.
+ * They store data in memory.
+ *
+ * Note: This file uses .remote.ts extension for naming consistency, but these are
+ * NOT actual SvelteKit remote functions. They are regular async functions that
+ * work in both test and library contexts.
+ *
+ * For actual remote functions in your app, see UserManagement.remote.ts template.
+ *
+ * To set initial data, use the resetState function:
+ * ```ts
+ * import { resetState } from './mockUserManagement.js';
+ * await resetState({ initialUsers: [...], simulateDelay: false });
+ * ```
+ */
+import type { User } from '../user-management.js';
+import type { GetUsersOptions, GetUsersResult } from './types.js';
+/**
+ * Reset mock adapter state
+ */
+export declare function resetState(options?: {
+    initialUsers?: User[];
+    simulateDelay?: boolean;
+    delayMs?: number;
+}): Promise<void>;
+/**
+ * Get users with pagination and sorting
+ * Matches UserManagementAdapter.getUsers signature
+ */
+export declare function getUsers(options: GetUsersOptions): Promise<GetUsersResult>;
+/**
+ * Create a new user
+ * Matches UserManagementAdapter.createUser signature
+ */
+export declare function createUser(userData: Partial<User>): Promise<User>;
+/**
+ * Update an existing user
+ * Matches UserManagementAdapter.updateUser signature
+ */
+export declare function updateUser(options: {
+    userId: string;
+    userData: Partial<User>;
+}): Promise<User>;
+/**
+ * Delete a single user
+ * Matches UserManagementAdapter.deleteUser signature
+ */
+export declare function deleteUser(userId: string): Promise<void>;
+/**
+ * Delete multiple users
+ * Matches UserManagementAdapter.deleteUsers signature
+ */
+export declare function deleteUsers(userIds: string[]): Promise<void>;
+/**
+ * Get permissions for a specific user
+ * Matches UserManagementAdapter.getUserPermissions signature
+ */
+export declare function getUserPermissions(userId: string): Promise<string[]>;
+/**
+ * Update permissions for a specific user
+ * Matches UserManagementAdapter.updateUserPermissions signature
+ */
+export declare function updateUserPermissions(options: {
+    userId: string;
+    permissions: string[];
+}): Promise<void>;

package/dist/user-management/adapters/mockUserManagement.js

@@ -0,0 +1,187 @@
+/**
+ * Mock User Management Functions
+ *
+ * Mock implementation of user management functions for testing and development.
+ * These are regular async functions that match the UserManagementAdapter interface.
+ * They store data in memory.
+ *
+ * Note: This file uses .remote.ts extension for naming consistency, but these are
+ * NOT actual SvelteKit remote functions. They are regular async functions that
+ * work in both test and library contexts.
+ *
+ * For actual remote functions in your app, see UserManagement.remote.ts template.
+ *
+ * To set initial data, use the resetState function:
+ * ```ts
+ * import { resetState } from './mockUserManagement.js';
+ * await resetState({ initialUsers: [...], simulateDelay: false });
+ * ```
+ */
+// Internal module-level state
+let mockUsers = [];
+let simulateDelay = false;
+let delayMs = 300;
+async function delay() {
+    if (simulateDelay) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+}
+/**
+ * Reset mock adapter state
+ */
+export async function resetState(options = {}) {
+    mockUsers = options.initialUsers || [];
+    simulateDelay = options.simulateDelay ?? false;
+    delayMs = options.delayMs ?? 300;
+}
+/**
+ * Get users with pagination and sorting
+ * Matches UserManagementAdapter.getUsers signature
+ */
+export async function getUsers(options) {
+    await delay();
+    let filteredUsers = [...mockUsers];
+    // Apply search query if provided
+    if (options.query) {
+        const query = options.query.toLowerCase();
+        filteredUsers = filteredUsers.filter((user) => user.first_name?.toLowerCase().includes(query) ||
+            user.last_name?.toLowerCase().includes(query) ||
+            user.username?.toLowerCase().includes(query) ||
+            user.email_addresses?.[0]?.email_address?.toLowerCase().includes(query));
+    }
+    // Apply sorting
+    if (options.sortBy) {
+        filteredUsers.sort((a, b) => {
+            let aValue = '';
+            let bValue = '';
+            switch (options.sortBy) {
+                case 'first_name':
+                    aValue = a.first_name || '';
+                    bValue = b.first_name || '';
+                    break;
+                case 'last_name':
+                    aValue = a.last_name || '';
+                    bValue = b.last_name || '';
+                    break;
+                case 'email_address':
+                    aValue = a.email_addresses?.[0]?.email_address || '';
+                    bValue = b.email_addresses?.[0]?.email_address || '';
+                    break;
+                case 'created_at':
+                    aValue = a.created_at || 0;
+                    bValue = b.created_at || 0;
+                    break;
+                case 'last_sign_in_at':
+                    aValue = a.last_sign_in_at || 0;
+                    bValue = b.last_sign_in_at || 0;
+                    break;
+                default:
+                    return 0;
+            }
+            if (typeof aValue === 'string' && typeof bValue === 'string') {
+                return options.sortOrder === 'desc'
+                    ? bValue.localeCompare(aValue)
+                    : aValue.localeCompare(bValue);
+            }
+            else if (typeof aValue === 'number' && typeof bValue === 'number') {
+                return options.sortOrder === 'desc' ? bValue - aValue : aValue - bValue;
+            }
+            return 0;
+        });
+    }
+    // Apply pagination
+    const start = (options.page - 1) * options.pageSize;
+    const end = start + options.pageSize;
+    const paginatedUsers = filteredUsers.slice(start, end);
+    return {
+        users: paginatedUsers,
+        totalUsers: filteredUsers.length
+    };
+}
+/**
+ * Create a new user
+ * Matches UserManagementAdapter.createUser signature
+ */
+export async function createUser(userData) {
+    await delay();
+    const newUser = {
+        id: `user_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+        first_name: userData.first_name || '',
+        last_name: userData.last_name || '',
+        username: userData.username,
+        email_addresses: userData.email_addresses || [{ email_address: '' }],
+        phone_numbers: userData.phone_numbers || [],
+        role: userData.role,
+        permissions: userData.permissions || [],
+        created_at: Date.now(),
+        ...userData
+    };
+    mockUsers.push(newUser);
+    return newUser;
+}
+/**
+ * Update an existing user
+ * Matches UserManagementAdapter.updateUser signature
+ */
+export async function updateUser(options) {
+    await delay();
+    const { userId, userData } = options;
+    const userIndex = mockUsers.findIndex((u) => u.id === userId);
+    if (userIndex === -1) {
+        throw new Error(`User with ID ${userId} not found`);
+    }
+    const updatedUser = {
+        ...mockUsers[userIndex],
+        ...userData,
+        id: userId // Ensure ID doesn't change
+    };
+    mockUsers[userIndex] = updatedUser;
+    return updatedUser;
+}
+/**
+ * Delete a single user
+ * Matches UserManagementAdapter.deleteUser signature
+ */
+export async function deleteUser(userId) {
+    await delay();
+    const userIndex = mockUsers.findIndex((u) => u.id === userId);
+    if (userIndex === -1) {
+        throw new Error(`User with ID ${userId} not found`);
+    }
+    mockUsers.splice(userIndex, 1);
+}
+/**
+ * Delete multiple users
+ * Matches UserManagementAdapter.deleteUsers signature
+ */
+export async function deleteUsers(userIds) {
+    await delay();
+    userIds.forEach((userId) => {
+        const userIndex = mockUsers.findIndex((u) => u.id === userId);
+        if (userIndex !== -1) {
+            mockUsers.splice(userIndex, 1);
+        }
+    });
+}
+/**
+ * Get permissions for a specific user
+ * Matches UserManagementAdapter.getUserPermissions signature
+ */
+export async function getUserPermissions(userId) {
+    await delay();
+    const user = mockUsers.find((u) => u.id === userId);
+    return user?.permissions || [];
+}
+/**
+ * Update permissions for a specific user
+ * Matches UserManagementAdapter.updateUserPermissions signature
+ */
+export async function updateUserPermissions(options) {
+    await delay();
+    const { userId, permissions } = options;
+    const user = mockUsers.find((u) => u.id === userId);
+    if (!user) {
+        throw new Error(`User with ID ${userId} not found`);
+    }
+    user.permissions = permissions;
+}

package/dist/user-management/adapters/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * User Management Adapter Types
+ *
+ * Shared types for user management adapters.
+ * These types are used by both remote function modules and the component.
+ */
+import type { User } from '../user-management.js';
+/**
+ * Options for fetching users
+ */
+export interface GetUsersOptions {
+    page: number;
+    pageSize: number;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+    query?: string;
+}
+/**
+ * Result of fetching users
+ */
+export interface GetUsersResult {
+    users: User[];
+    totalUsers: number;
+}

package/dist/user-management/adapters/types.js

@@ -0,0 +1,7 @@
+/**
+ * User Management Adapter Types
+ *
+ * Shared types for user management adapters.
+ * These types are used by both remote function modules and the component.
+ */
+export {};

package/dist/user-management/index.d.ts

@@ -7,4 +7,6 @@ export { default as UserTable } from './UserTable.svelte';
 export { default as UserModal } from './UserModal.svelte';
 export { default as UserViewModal } from './UserViewModal.svelte';
 export type { User, UserEmail, UserPhone, Permission, Role, UserTableProps, UserModalProps, UserViewModalProps, UserManagementProps, FormErrors } from './user-management.js';
+export type { GetUsersOptions, GetUsersResult } from './adapters/index.js';
+export type { UserManagementAdapter } from './user-management.js';
 export { createUser, getUserDisplayName, getUserInitials } from './user-management.js';

package/dist/user-management/user-management.d.ts

@@ -71,24 +71,51 @@ export interface UserViewModalProps {
     onClose: () => void;
     class?: ClassValue;
 }
+import type { GetUsersOptions, GetUsersResult } from './adapters/types.js';
+/**
+ * User Management Adapter Interface
+ *
+ * Defines the contract for user management adapters.
+ * Adapters can be remote function modules (returning RemoteQuery/RemoteCommand)
+ * or regular async function modules (returning Promise).
+ *
+ * Uses PromiseLike to accept both Promise and RemoteQuery/RemoteCommand types.
+ */
+export interface UserManagementAdapter {
+    getUsers: (options: GetUsersOptions) => PromiseLike<GetUsersResult>;
+    createUser: (userData: Partial<User>) => PromiseLike<User>;
+    updateUser: (options: {
+        userId: string;
+        userData: Partial<User>;
+    }) => PromiseLike<User>;
+    deleteUser: (userId: string) => PromiseLike<void>;
+    deleteUsers: (userIds: string[]) => PromiseLike<void>;
+    getUserPermissions: (userId: string) => PromiseLike<string[]>;
+    updateUserPermissions: (options: {
+        userId: string;
+        permissions: string[];
+    }) => PromiseLike<void>;
+}
 export interface UserManagementProps {
-    users: User[];
-    totalUsers: number;
-    loading?: boolean;
-    currentPage?: number;
-    pageSize?: number;
+    /**
+     * Adapter module containing remote functions or async functions
+     * Should be imported from a .remote.ts file
+     *
+     * Example:
+     * ```ts
+     * import * as adapter from './adapter.remote';
+     * <UserManagement adapter={adapter} roles={roles} />
+     * ```
+     */
+    adapter: UserManagementAdapter;
+    /**
+     * Available roles for user assignment
+     */
     roles?: Role[];
+    /**
+     * Available permissions for display (optional)
+     */
     permissions?: Permission[];
-    onPageChange: (page: number) => void;
-    onPageSizeChange: (size: number) => void;
-    onSort?: (state: {
-        column: string | null;
-        direction: 'asc' | 'desc' | null;
-    }) => void;
-    onCreateUser?: (userData: Partial<User>) => Promise<void>;
-    onUpdateUser?: (userId: string, userData: Partial<User>) => Promise<void>;
-    onDeleteUser?: (userId: string) => Promise<void>;
-    onDeleteUsers?: (userIds: string[]) => Promise<void>;
     class?: ClassValue;
 }
 export interface FormErrors {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@makolabs/ripple",
-	"version": "1.2.4",
+	"version": "1.2.8",
 	"description": "Simple Svelte 5 powered component library ✨",
 	"license": "SEE LICENSE IN LICENSE",
 	"repository": {
@@ -117,6 +117,7 @@
 	"dependencies": {
 		"@friendofsvelte/mermaid": "^0.0.4",
 		"@friendofsvelte/state": "^0.0.6-ts",
+		"@makolabs/ripple": "^1.2.4",
 		"@sveltejs/adapter-static": "^3.0.9",
 		"compromise": "^14.14.4",
 		"dayjs": "^1.11.13",