@agility/management-sdk 0.1.33 → 0.1.35

package/docs/instance-methods.md

@@ -0,0 +1,105 @@
+# InstanceMethods API Documentation
+
+The `InstanceMethods` class provides instance-level operations for retrieving configuration and settings.
+
+## Function List
+
+| Function | Description |
+|----------|-------------|
+| [getLocales](#getlocales) | Retrieves all available locales for the instance |
+
+---
+
+## getLocales
+
+Retrieves all available locales configured for the current Agility CMS instance.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| guid | string | Yes | The website GUID |
+
+### Returns
+
+`Promise<Locales[]>` - Array of locale objects with language configuration
+
+### Usage Example
+
+```typescript
+const locales = await client.instanceMethods.getLocales('your-guid');
+
+// Display available locales
+locales.forEach(locale => {
+  console.log(`${locale.name} (${locale.code})`);
+});
+
+// Find default locale
+const defaultLocale = locales.find(locale => locale.isDefault);
+console.log('Default locale:', defaultLocale.code);
+
+// Get all enabled locales
+const enabledLocales = locales.filter(locale => locale.isEnabled);
+console.log(`${enabledLocales.length} locales are enabled`);
+```
+
+### Locale Object Structure
+
+```typescript
+interface Locales {
+  code: string;           // Language code (e.g., 'en-us', 'fr-ca')
+  name: string;           // Display name (e.g., 'English (United States)')
+  isDefault: boolean;     // Whether this is the default locale
+  isEnabled: boolean;     // Whether this locale is enabled
+  // Additional locale properties may be available
+}
+```
+
+### Common Use Cases
+
+```typescript
+// Get locale codes for content operations
+const locales = await client.instanceMethods.getLocales(guid);
+const localeCodes = locales.map(locale => locale.code);
+
+// Use with content operations
+for (const localeCode of localeCodes) {
+  const content = await client.contentMethods.getContentItem(123, guid, localeCode);
+  console.log(`Content in ${localeCode}:`, content.fields.title);
+}
+
+// Check if a specific locale is available
+const hasSpanish = locales.some(locale => locale.code === 'es-es');
+if (hasSpanish) {
+  console.log('Spanish locale is available');
+}
+```
+
+---
+
+## Error Handling
+
+The method throws `Exception` objects on failure:
+
+```typescript
+try {
+  const locales = await client.instanceMethods.getLocales('your-guid');
+} catch (error) {
+  console.error('Failed to retrieve locales:', error.message);
+}
+```
+
+---
+
+## Navigation
+- [← Back to Main Documentation](../README.md)
+- [Authentication & Setup](./auth.md)
+- [AssetMethods](./asset-methods.md)
+- [BatchMethods](./batch-methods.md)
+- [ContainerMethods](./container-methods.md)
+- [ContentMethods](./content-methods.md)
+- [InstanceUserMethods](./instance-user-methods.md)
+- [ModelMethods](./model-methods.md)
+- [PageMethods](./page-methods.md)
+- [ServerUserMethods](./server-user-methods.md)
+- [WebhookMethods](./webhook-methods.md) 

package/docs/instance-user-methods.md

@@ -0,0 +1,231 @@
+# Agility CMS & Management API TypeScript SDK
+
+## InstanceUserMethods
+
+This class provides comprehensive user management operations for Agility CMS instances. These methods allow you to manage user accounts, roles, and permissions within your instance.
+
+**Important Notes:**
+- Instance user methods typically require administrative privileges
+- These operations affect user accounts across the entire instance
+- Role assignments control user access to different areas of the CMS
+- User management changes may affect website permissions and access
+
+### Function List
+- [getUsers](#getusers) - Retrieves all instance users
+- [saveUser](#saveuser) - Creates or updates an instance user
+- [deleteUser](#deleteuser) - Deletes an instance user by ID
+
+---
+
+### getUsers
+
+Retrieves all instance users for the current website.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | `string` | Yes | Current website GUID |
+
+**Returns:** `WebsiteUser` - Complete list of users with roles and permissions
+
+**Usage Example:**
+```typescript
+const users = await apiClient.instanceUserMethods.getUsers(guid);
+console.log(`User: ${user.firstName} ${user.lastName}`);
+console.log(`Email: ${user.emailAddress}`);
+console.log(`Role: ${user.roleName}`);
+console.log(`Status: ${user.isActive ? 'Active' : 'Inactive'}`);
+console.log(`Last Login: ${user.lastLoginDate}`);
+
+// Check user permissions
+if (user.permissions && user.permissions.length > 0) {
+    console.log('User permissions:');
+    user.permissions.forEach(permission => {
+        console.log(`  - ${permission}`);
+    });
+} else {
+    console.log('User has no specific permissions assigned');
+}
+
+// Check if user is an administrator
+const isAdmin = user.roleName === 'Administrator' || 
+               user.roleName === 'Instance Administrator';
+console.log(`Is Administrator: ${isAdmin}`);
+```
+
+**Response Properties:**
+The `InstanceUser` object includes:
+- `userID`: Unique identifier for the user
+- `firstName`: User's first name
+- `lastName`: User's last name
+- `emailAddress`: User's email address
+- `roleName`: The user's role within the instance
+- `isActive`: Whether the user account is active
+- `lastLoginDate`: Date of the user's last login
+- `createdDate`: Date the user account was created
+- `permissions`: Array of specific permissions assigned to the user
+
+**Error Handling:**
+- Throws `Exception` when user not found
+- Throws `Exception` when insufficient permissions to view user details
+
+### saveUser
+
+Creates a new instance user or updates an existing one.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `emailAddress` | `string` | Yes | User's email address |
+| `roles` | `InstanceRole[]` | Yes | Array of roles to assign to user |
+| `guid` | `string` | Yes | Current website GUID |
+| `firstName` | `string` | No | User's first name |
+| `lastName` | `string` | No | User's last name |
+
+**Returns:** `InstanceUser` - Saved user object with updated metadata
+
+**Usage Example:**
+```typescript
+// Create a new user
+const roles = [
+    { roleID: 1, roleName: 'Editor' },
+    { roleID: 2, roleName: 'Contributor' }
+];
+
+const savedUser = await apiClient.instanceUserMethods.saveUser(
+    'john.doe@company.com',
+    roles,
+    guid,
+    'John',
+    'Doe'
+);
+console.log('User created with ID:', savedUser.userID);
+
+// Update existing user
+const existingUser = await apiClient.instanceUserMethods.getInstanceUser(123, guid);
+existingUser.firstName = 'Jane';
+existingUser.roleName = 'Administrator';
+existingUser.isActive = false; // Deactivate user
+
+const updatedUser = await apiClient.instanceUserMethods.saveInstanceUser(existingUser, guid);
+console.log('User updated:', updatedUser.emailAddress);
+
+// Bulk user role update
+const updateUserRole = async (userID, newRole) => {
+    const user = await apiClient.instanceUserMethods.getInstanceUser(userID, guid);
+    user.roleName = newRole;
+    return await apiClient.instanceUserMethods.saveInstanceUser(user, guid);
+};
+
+// Promote user to administrator
+await updateUserRole(123, 'Administrator');
+```
+
+**User Roles:**
+Common role names include:
+- `Administrator`: Full access to all instance features
+- `Instance Administrator`: Instance-level administrative access
+- `Editor`: Content creation and editing permissions
+- `Publisher`: Content publishing permissions
+- `Contributor`: Limited content creation permissions
+- `Viewer`: Read-only access
+
+**Validation Rules:**
+- `emailAddress` must be unique within the instance
+- `password` is required for new users (not needed for updates)
+- `firstName` and `lastName` are required
+- `roleName` must be a valid role within the instance
+
+**Error Handling:**
+- Throws `Exception` when validation fails (duplicate email, invalid role, etc.)
+- Throws `Exception` when save operation fails
+- Throws `Exception` when insufficient permissions to create/update users
+
+### deleteUser
+
+Deletes an instance user by their unique ID.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | `number` | Yes | The user ID to delete |
+| `guid` | `string` | Yes | Current website GUID |
+
+**Returns:** `string` - Confirmation message of successful deletion
+
+**Usage Example:**
+```typescript
+try {
+    const result = await apiClient.instanceUserMethods.deleteUser(123, guid);
+    console.log(result); // "User deleted successfully"
+} catch (error) {
+    if (error.message.includes('owns content')) {
+        console.log('Cannot delete user: user owns content items');
+        // Handle by reassigning content or archiving user instead
+    } else if (error.message.includes('last administrator')) {
+        console.log('Cannot delete user: last administrator in instance');
+    } else {
+        console.error('Failed to delete user:', error.message);
+    }
+}
+
+// Safe user deletion with checks
+const safeDeleteUser = async (userID) => {
+    try {
+        // Get user details first
+        const user = await apiClient.instanceUserMethods.getInstanceUser(userID, guid);
+        console.log(`Attempting to delete user: ${user.emailAddress}`);
+        
+        // Check if user is active
+        if (user.isActive) {
+            console.log('Warning: Deleting active user');
+        }
+        
+        // Perform deletion
+        const result = await apiClient.instanceUserMethods.deleteInstanceUser(userID, guid);
+        console.log('User deleted successfully');
+        return result;
+    } catch (error) {
+        console.error('Failed to delete user:', error.message);
+        throw error;
+    }
+};
+
+// Alternative: Deactivate instead of delete
+const deactivateUser = async (userID) => {
+    const user = await apiClient.instanceUserMethods.getInstanceUser(userID, guid);
+    user.isActive = false;
+    return await apiClient.instanceUserMethods.saveInstanceUser(user, guid);
+};
+```
+
+**Deletion Restrictions:**
+- Cannot delete a user who owns content items (reassign content first)
+- Cannot delete the last administrator in the instance
+- Cannot delete your own user account
+- Cannot delete users with active sessions (in some cases)
+
+**Best Practices:**
+- Consider deactivating users instead of deleting them to preserve audit trails
+- Reassign content ownership before deleting users
+- Ensure at least one administrator remains in the instance
+- Log user deletions for security auditing
+
+**Error Handling:**
+- Throws `Exception` when user not found
+- Throws `Exception` when user cannot be deleted (owns content, last admin, etc.)
+- Throws `Exception` when insufficient permissions to delete users
+
+---
+
+## Navigation
+- [← Back to Main Documentation](../README.md)
+- [Authentication & Setup](./auth.md)
+- [Multi-Instance Operations](./multi-instance-operations.md)
+- [AssetMethods](./asset-methods.md)
+- [BatchMethods](./batch-methods.md)
+- [ContainerMethods](./container-methods.md)
+- [ContentMethods](./content-methods.md)
+- [InstanceMethods](./instance-methods.md)
+- **InstanceUserMethods** *(current)*
+- [ModelMethods](./model-methods.md)
+- [PageMethods](./page-methods.md)
+- [ServerUserMethods](./server-user-methods.md)
+- [WebhookMethods](./webhook-methods.md)