@makolabs/ripple 1.2.3 → 1.2.8

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>;