@simpleapps-com/augur-api 0.2.3 → 0.2.5

package/dist/esm/services/joomla/client.js

@@ -33,50 +33,91 @@ export class JoomlaClient extends BaseServiceClient {
         this.content = {
             /**
              * Retrieve a paginated list of content items
-             * @description Returns all content with optional filtering, pagination, and edge caching
+             * @description Returns articles, documents, and content with filtering, pagination, and edge caching capabilities
+             * @fullPath api.joomla.content.list
+             * @service joomla
+             * @domain content-management
+             * @dataMethod listData() - returns only the content array without metadata
+             * @pagination Uses count, total, totalResults for pagination metadata. Supports limit/offset parameters.
+             * @caching Supports edgeCache parameter (1-8 hours) for improved performance on content that changes infrequently
+             * @discoverable true
+             * @searchTerms ["content", "articles", "list content", "cms content", "documents", "blog posts"]
+             * @relatedEndpoints ["api.joomla.content.get", "api.joomla.content.getDoc", "api.joomla.tags.list"]
+             * @commonPatterns ["list articles", "get content", "blog content", "cms articles", "filter content"]
              * @param params Optional filtering, pagination, and caching parameters
-             * @param params.edgeCache Optional cache duration in hours (1, 2, 3, 4, 5, 8)
-             * @returns Array of content items
+             * @param params.categoryIdList Comma-separated list of category IDs to filter content (e.g., '1,2,3')
+             * @param params.q Search query for filtering content by title/text
+             * @param params.limit Maximum number of content items to return (default: 20, max: 100)
+             * @param params.offset Number of items to skip for pagination (default: 0)
+             * @param params.edgeCache Cache duration in hours (1, 2, 3, 4, 5, 8) - recommended for content
+             * @returns BaseResponse<ContentItem[]> with pagination metadata and content array
              * @throws ValidationError When parameters are invalid or response is malformed
              * @example
              * ```typescript
-             * // Get all content
-             * const content = await client.content.list();
+             * // Get all content with full response metadata
+             * const response = await api.joomla.content.list();
+             * console.log(`Found ${response.total} articles, showing ${response.data.length}`);
              *
-             * // Get filtered content
-             * const filtered = await client.content.list({
+             * // Filter content by categories with search
+             * const filtered = await api.joomla.content.list({
              *   categoryIdList: '1,2,3',
-             *   limit: 20,
-             *   q: 'search term'
+             *   q: 'product review',
+             *   limit: 10
              * });
              *
-             * // Get content with 4-hour edge caching
-             * const cached = await client.content.list({
-             *   edgeCache: 4,  // Cache for 4 hours
-             *   categoryIdList: '1,2,3',
+             * // Get just content data without metadata
+             * const articles = await api.joomla.content.listData({
+             *   categoryIdList: '5',
              *   limit: 20
              * });
+             * articles.forEach(article => console.log(article.title, article.alias));
+             *
+             * // Use aggressive caching for content (recommended)
+             * const cachedContent = await api.joomla.content.list({
+             *   edgeCache: 4,  // Cache for 4 hours - content changes infrequently
+             *   categoryIdList: '1,2,3'
+             * });
              * ```
              */
             list: this.createListMethod('/content', ContentListParamsSchema, ContentListResponseSchema),
             /**
-             * Get content details by ID
-             * @description Returns a single content item by its ID or alias with optional edge caching
-             * @param contentId Content ID (number) or alias lookup (use 0 with params.alias)
+             * Get content details by ID or alias
+             * @description Returns a single content item by its ID or alias with optional edge caching and full content metadata
+             * @fullPath api.joomla.content.get
+             * @service joomla
+             * @domain content-management
+             * @dataMethod getData(contentId, params) - returns only the content object without metadata
+             * @caching Supports edgeCache parameter (1-8 hours) for improved performance
+             * @aliasLookup Supports alias-based lookup by using contentId=0 with params.alias
+             * @discoverable true
+             * @searchTerms ["get content", "content details", "article details", "content by id", "single content"]
+             * @relatedEndpoints ["api.joomla.content.list", "api.joomla.content.getDoc", "api.joomla.tags.list"]
+             * @commonPatterns ["get content by id", "fetch article", "content details lookup", "get by alias"]
+             * @param contentId Content ID (number) or use 0 for alias lookup
              * @param params Optional parameters for alias lookup and caching
-             * @param params.edgeCache Optional cache duration in hours (1, 2, 3, 4, 5, 8)
-             * @returns Content item details
+             * @param params.alias Content alias for lookup when contentId is 0
+             * @param params.catid Category ID for alias lookup specificity
+             * @param params.edgeCache Cache duration in hours (1, 2, 3, 4, 5, 8) for improved performance
+             * @returns BaseResponse<ContentItem> with complete content details and metadata
              * @throws ValidationError When parameters are invalid or response is malformed
              * @example
              * ```typescript
-             * // Get by ID
-             * const content = await client.content.get(123);
+             * // Get content by ID with full response metadata
+             * const response = await api.joomla.content.get(123);
+             * console.log('Article:', response.data.title, 'Status:', response.status);
+             *
+             * // Get content by alias
+             * const byAlias = await api.joomla.content.get(0, {
+             *   alias: 'my-article',
+             *   catid: 45
+             * });
              *
-             * // Get by alias
-             * const content = await client.content.get(0, { alias: 'my-article', catid: 45 });
+             * // Get just content data without metadata
+             * const article = await api.joomla.content.getData(123);
+             * console.log(article.title, article.introtext, article.fulltext);
              *
-             * // Get with 8-hour edge caching
-             * const cachedContent = await client.content.get(123, { edgeCache: 8 });
+             * // Use edge caching for frequently accessed content
+             * const cachedContent = await api.joomla.content.get(123, { edgeCache: 8 });
              * ```
              */
             get: async (contentId, params) => {
@@ -100,6 +141,40 @@ export class JoomlaClient extends BaseServiceClient {
              * ```
              */
             getDoc: this.createDocMethod('/content/{id}/doc', ContentDocumentResponseSchema),
+            /**
+             * Retrieve a paginated list of content items (data only)
+             * @description Returns only the data array from content items response
+             * @param params Optional filtering, pagination, and caching parameters
+             * @returns Array of content items (data only)
+             * @throws ValidationError When parameters are invalid or response is malformed
+             */
+            listData: async (params) => {
+                const response = await this.content.list(params);
+                return response.data;
+            },
+            /**
+             * Get content details by ID (data only)
+             * @description Returns only the data from content item details response
+             * @param contentId Content ID (number) or alias lookup (use 0 with params.alias)
+             * @param params Optional parameters for alias lookup and caching
+             * @returns Content item details (data only)
+             * @throws ValidationError When parameters are invalid or response is malformed
+             */
+            getData: async (contentId, params) => {
+                const response = await this.content.get(contentId, params);
+                return response.data;
+            },
+            /**
+             * Get content documentation (data only)
+             * @description Returns only the data from enhanced content document response
+             * @param contentId Content ID (number) or alias lookup (use 0 with query params)
+             * @returns Enhanced content document (data only)
+             * @throws ValidationError When response is malformed
+             */
+            getDocData: async (contentId) => {
+                const response = await this.content.getDoc(contentId);
+                return response.data;
+            },
         };
         /**
          * User endpoints
@@ -108,43 +183,80 @@ export class JoomlaClient extends BaseServiceClient {
         this.users = {
             /**
              * Retrieve a paginated list of users
-             * @description Returns all users with optional filtering, pagination, and edge caching
+             * @description Returns all users with optional filtering, pagination, and edge caching for user management operations
+             * @fullPath api.joomla.users.list
+             * @service joomla
+             * @domain user-management
+             * @dataMethod listData() - returns only the user array without metadata
+             * @pagination Uses count, total, totalResults for pagination metadata. Supports limit/offset parameters.
+             * @caching Supports edgeCache parameter (1-8 hours) for improved performance
+             * @discoverable true
+             * @searchTerms ["users", "list users", "get users", "user management", "accounts", "profiles"]
+             * @relatedEndpoints ["api.joomla.userGroups.list", "api.customers.customer.list", "api.joomla.users.get"]
+             * @commonPatterns ["list all users", "search users", "paginate users", "filter users"]
              * @param params Optional filtering, pagination, and caching parameters
-             * @param params.edgeCache Optional cache duration in hours (1, 2, 3, 4, 5, 8)
-             * @returns Paginated user list with total count
+             * @param params.q Search query for filtering users by username/email
+             * @param params.limit Maximum number of users to return (default: 20, max: 100)
+             * @param params.offset Number of users to skip for pagination (default: 0)
+             * @param params.edgeCache Cache duration in hours (1, 2, 3, 4, 5, 8) for improved performance
+             * @returns BaseResponse<User[]> with pagination metadata and user array
              * @throws ValidationError When parameters are invalid or response is malformed
              * @example
              * ```typescript
-             * // Get all users
-             * const users = await client.users.list();
-             * console.log(`Found ${users.total} users, showing ${users.data.length}`);
+             * // Get all users with full response metadata
+             * const response = await api.joomla.users.list();
+             * console.log(`Found ${response.total} users, showing ${response.data.length}`);
+             * console.log('Pagination:', { count: response.count, total: response.total });
              *
-             * // Search users
-             * const searchResults = await client.users.list({ q: 'admin', limit: 5 });
+             * // Search users with filtering
+             * const searchResults = await api.joomla.users.list({
+             *   q: 'admin',
+             *   limit: 10,
+             *   offset: 0
+             * });
              *
-             * // Get users with 2-hour edge caching
-             * const cachedUsers = await client.users.list({
+             * // Get just user data without metadata (using data method)
+             * const users = await api.joomla.users.listData({ limit: 20 });
+             * users.forEach(user => console.log(user.username, user.email));
+             *
+             * // Use edge caching for performance
+             * const cachedUsers = await api.joomla.users.list({
              *   edgeCache: 2,  // Cache for 2 hours
-             *   limit: 20
+             *   limit: 50
              * });
              * ```
              */
             list: this.createListMethod('/users', UserListParamsSchema, UserListResponseSchema),
             /**
              * Get user details by ID
-             * @description Returns detailed information for a specific user with optional edge caching
-             * @param userId User ID (number or string)
+             * @description Returns detailed information for a specific user including profile data and metadata
+             * @fullPath api.joomla.users.get
+             * @service joomla
+             * @domain user-management
+             * @dataMethod getData(userId, params) - returns only the user object without metadata
+             * @caching Supports edgeCache parameter (1-8 hours) for improved performance
+             * @discoverable true
+             * @searchTerms ["get user", "user details", "user profile", "user by id", "single user"]
+             * @relatedEndpoints ["api.joomla.users.list", "api.joomla.users.getDoc", "api.joomla.users.getTrinityDoc"]
+             * @commonPatterns ["get user by id", "fetch user profile", "user details lookup"]
+             * @param userId User ID (number or string) - the unique identifier for the user
              * @param params Optional caching parameters
-             * @param params.edgeCache Optional cache duration in hours (1, 2, 3, 4, 5, 8)
-             * @returns User details including profile information
-             * @throws ValidationError When response is malformed
+             * @param params.edgeCache Cache duration in hours (1, 2, 3, 4, 5, 8) for improved performance
+             * @returns BaseResponse<User> with complete user details and metadata
+             * @throws ValidationError When userId is invalid or response is malformed
              * @example
              * ```typescript
-             * const user = await client.users.get(123);
+             * // Get user with full response metadata
+             * const response = await api.joomla.users.get(123);
+             * console.log('User:', response.data.username, response.data.email);
+             * console.log('Status:', response.status, response.message);
+             *
+             * // Get just user data without metadata
+             * const user = await api.joomla.users.getData(123);
              * console.log(user.username, user.email, user.registerDate);
              *
-             * // Get with 1-hour edge caching
-             * const cachedUser = await client.users.get(123, { edgeCache: 1 });
+             * // Use edge caching for frequently accessed users
+             * const cachedUser = await api.joomla.users.get(123, { edgeCache: 1 });
              * ```
              */
             get: this.createGetMethod('/users/{id}', UserResponseSchema),
@@ -198,15 +310,32 @@ export class JoomlaClient extends BaseServiceClient {
              */
             groups: {
                 /**
-                 * Get user's groups
-                 * @description Returns all groups that a specific user belongs to
-                 * @param userId User ID (string)
+                 * Get user's group memberships
+                 * @description Returns all groups that a specific user belongs to with membership details
+                 * @fullPath api.joomla.users.groups.list
+                 * @service joomla
+                 * @domain user-management
+                 * @dataMethod listData(userId, params) - returns only the group memberships array without metadata
+                 * @discoverable true
+                 * @searchTerms ["user groups", "group membership", "user permissions", "user roles"]
+                 * @relatedEndpoints ["api.joomla.userGroups.list", "api.joomla.users.groups.createMapping", "api.joomla.users.get"]
+                 * @commonPatterns ["get user groups", "user permissions", "group membership", "user roles"]
+                 * @param userId User ID (string) - the unique identifier for the user
                  * @param params Optional pagination parameters
-                 * @returns Array of user group memberships
+                 * @param params.limit Maximum number of group memberships to return (default: 20)
+                 * @param params.offset Number of memberships to skip for pagination (default: 0)
+                 * @returns BaseResponse<UserGroupMembership[]> with group membership details and metadata
                  * @throws ValidationError When response is malformed
                  * @example
                  * ```typescript
-                 * const groups = await client.users.groups.list('123');
+                 * // Get user's groups with full response metadata
+                 * const response = await api.joomla.users.groups.list('123');
+                 * response.data.forEach(group => {
+                 *   console.log(`Group: ${group.title} (ID: ${group.groupId})`);
+                 * });
+                 *
+                 * // Get just group memberships data without metadata
+                 * const groups = await api.joomla.users.groups.listData('123');
                  * groups.forEach(group => console.log(group.title, group.groupId));
                  * ```
                  */
@@ -259,29 +388,88 @@ export class JoomlaClient extends BaseServiceClient {
                         responseSchema: UserGroupMappingResponseSchema,
                     }, request, { id: String(userId) });
                 },
+                /**
+                 * Get user's groups (data only)
+                 * @description Returns only the data array from user group memberships response
+                 * @param userId User ID (string)
+                 * @param params Optional pagination parameters
+                 * @returns Array of user group memberships (data only)
+                 * @throws ValidationError When response is malformed
+                 */
+                listData: async (userId, params) => {
+                    const response = await this.users.groups.list(userId, params);
+                    return response.data;
+                },
+                /**
+                 * Get specific user group membership (data only)
+                 * @description Returns only the data from user group membership details response
+                 * @param userId User ID (string)
+                 * @param groupId Group ID (number or string)
+                 * @returns User group membership details (data only)
+                 * @throws ValidationError When response is malformed
+                 */
+                getData: async (userId, groupId) => {
+                    const response = await this.users.groups.get(userId, groupId);
+                    return response.data;
+                },
+                /**
+                 * Create or update user group mapping (data only)
+                 * @description Returns only the data from created/updated group mapping response
+                 * @param userId User ID (number or string)
+                 * @param request Group mapping request data
+                 * @returns Group mapping information (data only)
+                 * @throws ValidationError When request is invalid or response is malformed
+                 */
+                createMappingData: async (userId, request) => {
+                    const response = await this.users.groups.createMapping(userId, request);
+                    return response.data;
+                },
             },
             /**
-             * Verify user password
-             * @description Verifies if the provided username and password are valid, supporting cross-site authentication
-             *
-             * Cross-site authentication:
-             * - When called from 'augur_info' site, can authenticate users from any other site
-             * - Include optional 'siteId' parameter to authenticate against a different site
-             * - Returned JWT token will be scoped to the target site, not augur_info
-             *
-             * @param request Object containing username, password, and optional siteId for cross-site auth
-             * @returns Object with verification status, user ID, username, token (if verified), and email
-             *
+             * Verify user credentials and authenticate
+             * @description Verifies username/password combination and returns authentication token, supports cross-site authentication
+             * @fullPath api.joomla.users.verifyPassword
+             * @service joomla
+             * @domain authentication
+             * @dataMethod verifyPasswordData(request) - returns only the verification result without metadata
+             * @crossSite Supports authentication across multiple sites when called from 'augur_info' site
+             * @discoverable true
+             * @searchTerms ["verify password", "authenticate", "login", "user authentication", "credentials", "sign in"]
+             * @relatedEndpoints ["api.joomla.users.get", "api.joomla.users.create", "api.customers.customer.get"]
+             * @commonPatterns ["user login", "authenticate user", "verify credentials", "password check"]
+             * @param request Authentication request containing username, password, and optional siteId
+             * @param request.username User's username for authentication
+             * @param request.password User's password for verification
+             * @param request.siteId Optional site ID for cross-site authentication (when using augur_info)
+             * @returns BaseResponse<VerifyPasswordResult> with verification status, user info, and JWT token
+             * @throws ValidationError When credentials are invalid or request is malformed
              * @example
-             * // Standard authentication
-             * await client.users.verifyPassword({ username: 'user', password: 'pass' });
+             * ```typescript
+             * // Standard authentication with full response
+             * const response = await api.joomla.users.verifyPassword({
+             *   username: 'johndoe',
+             *   password: 'securePassword123'
+             * });
              *
-             * // Cross-site authentication (when using augur_info as x-site-id header)
-             * await client.users.verifyPassword({
-             *   username: 'user',
-             *   password: 'pass',
+             * if (response.data.verified) {
+             *   console.log('Login successful:', response.data.username);
+             *   console.log('JWT Token:', response.data.token);
+             *   console.log('User ID:', response.data.userId);
+             * }
+             *
+             * // Cross-site authentication (when using augur_info site)
+             * const crossSiteAuth = await api.joomla.users.verifyPassword({
+             *   username: 'johndoe',
+             *   password: 'securePassword123',
              *   siteId: 'customer_site_1'
              * });
+             *
+             * // Get just verification data without metadata
+             * const authResult = await api.joomla.users.verifyPasswordData({
+             *   username: 'johndoe',
+             *   password: 'securePassword123'
+             * });
+             * ```
              */
             verifyPassword: async (request) => {
                 return this.executeRequest({
@@ -292,20 +480,43 @@ export class JoomlaClient extends BaseServiceClient {
                 }, request);
             },
             /**
-             * Create a new user
-             * @description Creates a new user account in the system
+             * Create a new user account
+             * @description Creates a new user account in the system with username, email, name, and password
+             * @fullPath api.joomla.users.create
+             * @service joomla
+             * @domain user-management
+             * @dataMethod createData(request) - returns only the created user object without metadata
+             * @discoverable true
+             * @searchTerms ["create user", "new user", "user registration", "add user", "register user"]
+             * @relatedEndpoints ["api.joomla.users.list", "api.joomla.users.get", "api.joomla.users.verifyPassword"]
+             * @commonPatterns ["register new user", "create account", "add user account", "user signup"]
              * @param request User creation request data including username, email, name, and password
-             * @returns Created user information with ID, username, and email
+             * @param request.username Unique username for the new user (required)
+             * @param request.email Valid email address for the user (required)
+             * @param request.name Full display name for the user (required)
+             * @param request.password Secure password for the user (required, minimum 8 characters)
+             * @returns BaseResponse<User> with created user information including ID, username, and email
              * @throws ValidationError When request is invalid or response is malformed
              * @example
              * ```typescript
-             * const newUser = await client.users.create({
+             * // Create new user with full response metadata
+             * const response = await api.joomla.users.create({
              *   username: 'newuser',
              *   email: 'user@example.com',
              *   name: 'New User',
              *   password: 'SecurePass123!'
              * });
-             * console.log('Created user:', newUser.id, newUser.username);
+             * console.log('Created user:', response.data.id, response.data.username);
+             * console.log('Status:', response.status, response.message);
+             *
+             * // Get just created user data without metadata
+             * const newUser = await api.joomla.users.createData({
+             *   username: 'johndoe',
+             *   email: 'john@example.com',
+             *   name: 'John Doe',
+             *   password: 'MySecurePassword123!'
+             * });
+             * console.log('New user ID:', newUser.id, 'Email:', newUser.email);
              * ```
              */
             create: this.createCreateMethod('/users', CreateUserRequestSchema, CreateUserResponseSchema),
@@ -342,6 +553,96 @@ export class JoomlaClient extends BaseServiceClient {
              * ```
              */
             block: this.createDeleteMethod('/users/{id}', BlockUserResponseSchema),
+            /**
+             * Retrieve a paginated list of users (data only)
+             * @description Returns only the data array from users response
+             * @param params Optional filtering, pagination, and caching parameters
+             * @returns Array of users (data only)
+             * @throws ValidationError When parameters are invalid or response is malformed
+             */
+            listData: async (params) => {
+                const response = await this.users.list(params);
+                return response.data;
+            },
+            /**
+             * Get user details by ID (data only)
+             * @description Returns only the data from user details response
+             * @param userId User ID (number or string)
+             * @param params Optional caching parameters
+             * @returns User details (data only)
+             * @throws ValidationError When response is malformed
+             */
+            getData: async (userId, params) => {
+                const response = await this.users.get(userId, params);
+                return response.data;
+            },
+            /**
+             * Get user documentation (data only)
+             * @description Returns only the data from enhanced user document response
+             * @param userId User ID (number or string)
+             * @returns Enhanced user document (data only)
+             * @throws ValidationError When response is malformed
+             */
+            getDocData: async (userId) => {
+                const response = await this.users.getDoc(userId);
+                return response.data;
+            },
+            /**
+             * Get Trinity user documentation (data only)
+             * @description Returns only the data from specialized Trinity business logic document response
+             * @param userId User ID (number or string)
+             * @param params Optional filtering and pagination parameters
+             * @returns Trinity document (data only)
+             * @throws ValidationError When parameters are invalid or response is malformed
+             */
+            getTrinityDocData: async (userId, params) => {
+                const response = await this.users.getTrinityDoc(userId, params);
+                return response.data;
+            },
+            /**
+             * Verify user password (data only)
+             * @description Returns only the data from password verification response
+             * @param request Object containing username, password, and optional siteId for cross-site auth
+             * @returns Verification result (data only)
+             */
+            verifyPasswordData: async (request) => {
+                const response = await this.users.verifyPassword(request);
+                return response.data;
+            },
+            /**
+             * Create a new user (data only)
+             * @description Returns only the data from created user response
+             * @param request User creation request data including username, email, name, and password
+             * @returns Created user information (data only)
+             * @throws ValidationError When request is invalid or response is malformed
+             */
+            createData: async (request) => {
+                const response = await this.users.create(request);
+                return response.data;
+            },
+            /**
+             * Update an existing user (data only)
+             * @description Returns only the data from updated user response
+             * @param userId User ID (number or string)
+             * @param request User update data with optional fields to modify
+             * @returns Updated user object (data only)
+             * @throws ValidationError When request is invalid or response is malformed
+             */
+            updateData: async (userId, request) => {
+                const response = await this.users.update(userId, request);
+                return response.data;
+            },
+            /**
+             * Block (deactivate) a user (data only)
+             * @description Returns only the data from user blocking response
+             * @param userId User ID (number or string)
+             * @returns Blocking operation result (data only)
+             * @throws ValidationError When response is malformed
+             */
+            blockData: async (userId) => {
+                const response = await this.users.block(userId);
+                return response.data;
+            },
         };
         /**
          * User Groups endpoints
@@ -349,31 +650,47 @@ export class JoomlaClient extends BaseServiceClient {
          */
         this.userGroups = {
             /**
-             * Get user groups
-             * @description Returns hierarchical list of user groups with optional filtering, ordering, and edge caching
+             * Get hierarchical list of user groups
+             * @description Returns system-wide user groups with hierarchy information, filtering, and caching
+             * @fullPath api.joomla.userGroups.list
+             * @service joomla
+             * @domain user-management
+             * @dataMethod listData(params) - returns only the user groups array without metadata
+             * @hierarchy Returns groups with level and parent relationship information
+             * @caching Supports edgeCache parameter (1-8 hours) - recommended since groups rarely change
+             * @discoverable true
+             * @searchTerms ["user groups", "groups", "permissions", "roles", "group hierarchy", "user roles"]
+             * @relatedEndpoints ["api.joomla.users.groups.list", "api.joomla.users.list", "api.joomla.users.groups.createMapping"]
+             * @commonPatterns ["list user groups", "get groups", "group permissions", "user roles", "group hierarchy"]
              * @param params Optional filtering, ordering, and caching parameters
-             * @param params.edgeCache Optional cache duration in hours (1, 2, 3, 4, 5, 8)
-             * @returns Array of user groups with hierarchy information
+             * @param params.orderBy Sort order (e.g., 'title|ASC', 'title|DESC', 'level|ASC')
+             * @param params.parentIdList Comma-separated list of parent group IDs to filter (e.g., '1,2')
+             * @param params.edgeCache Cache duration in hours (1-8) - highly recommended since groups rarely change
+             * @returns BaseResponse<UserGroup[]> with hierarchy metadata and groups array
              * @throws ValidationError When parameters are invalid or response is malformed
              * @example
              * ```typescript
-             * // Get all user groups
-             * const groups = await client.userGroups.list();
+             * // Get all user groups with hierarchy information
+             * const response = await api.joomla.userGroups.list();
+             * response.data.forEach(group => {
+             *   console.log(`${group.title} (Level: ${group.level}, Parent: ${group.parentId})`);
+             * });
              *
-             * // Get filtered groups
-             * const filtered = await client.userGroups.list({
-             *   orderBy: 'title|DESC',
+             * // Filter and order groups
+             * const ordered = await api.joomla.userGroups.list({
+             *   orderBy: 'title|ASC',
              *   parentIdList: '1,2'
              * });
              *
-             * // Get groups with 8-hour edge caching (groups rarely change)
-             * const cachedGroups = await client.userGroups.list({
-             *   edgeCache: 8,  // Cache for 8 hours
-             *   orderBy: 'title|ASC'
+             * // Get just groups data without metadata
+             * const groups = await api.joomla.userGroups.listData({
+             *   orderBy: 'level|ASC'
              * });
              *
-             * groups.forEach(group => {
-             *   console.log(`${group.title} (Level: ${group.level})`);
+             * // Use long caching since groups rarely change
+             * const cachedGroups = await api.joomla.userGroups.list({
+             *   edgeCache: 8,  // Cache for 8 hours - groups change very infrequently
+             *   orderBy: 'title|ASC'
              * });
              * ```
              */
@@ -385,6 +702,17 @@ export class JoomlaClient extends BaseServiceClient {
                     responseSchema: UserGroupListResponseSchema,
                 }, params);
             },
+            /**
+             * Get user groups (data only)
+             * @description Returns only the data array from user groups response
+             * @param params Optional filtering, ordering, and caching parameters
+             * @returns Array of user groups (data only)
+             * @throws ValidationError When parameters are invalid or response is malformed
+             */
+            listData: async (params) => {
+                const response = await this.userGroups.list(params);
+                return response.data;
+            },
         };
         /**
          * Tags endpoints
@@ -392,36 +720,66 @@ export class JoomlaClient extends BaseServiceClient {
          */
         this.tags = {
             /**
-             * Get tags
-             * @description Returns hierarchical list of content tags with optional filtering, search, and edge caching
+             * Get hierarchical list of content tags
+             * @description Returns content tags with hierarchy, usage information, filtering, search, and edge caching
+             * @fullPath api.joomla.tags.list
+             * @service joomla
+             * @domain content-management
+             * @dataMethod listData(params) - returns only the tags array without metadata
+             * @hierarchy Returns tags with level and parent relationship information
+             * @caching Supports edgeCache parameter (1-8 hours) - recommended for reference data
+             * @discoverable true
+             * @searchTerms ["tags", "content tags", "taxonomy", "categories", "tag hierarchy"]
+             * @relatedEndpoints ["api.joomla.content.list", "api.joomla.content.get", "api.joomla.userGroups.list"]
+             * @commonPatterns ["list tags", "get tags", "search tags", "content taxonomy", "tag filtering"]
              * @param params Optional filtering, search, and caching parameters
-             * @param params.edgeCache Optional cache duration in hours (1, 2, 3, 4, 5, 8)
-             * @returns Array of tags with hierarchy and usage information
+             * @param params.q Search query for filtering tags by title
+             * @param params.catId Category ID to filter tags by category
+             * @param params.limit Maximum number of tags to return (default: 20, max: 100)
+             * @param params.offset Number of tags to skip for pagination (default: 0)
+             * @param params.edgeCache Cache duration in hours (1-8) - recommended for reference data
+             * @returns BaseResponse<Tag[]> with hierarchy metadata and tags array
              * @throws ValidationError When parameters are invalid or response is malformed
              * @example
              * ```typescript
-             * // Get all tags
-             * const tags = await client.tags.list();
+             * // Get all tags with hierarchy information
+             * const response = await api.joomla.tags.list();
+             * response.data.forEach(tag => {
+             *   console.log(`${tag.title} (${tag.hits} hits, Level: ${tag.level})`);
+             * });
              *
-             * // Search tags
-             * const searchTags = await client.tags.list({
+             * // Search tags by keyword
+             * const searchTags = await api.joomla.tags.list({
              *   q: 'technology',
              *   catId: 1,
              *   limit: 10
              * });
              *
-             * // Get tags with 5-hour edge caching (reference data)
-             * const cachedTags = await client.tags.list({
-             *   edgeCache: 5,  // Cache for 5 hours
+             * // Get just tags data without metadata
+             * const tags = await api.joomla.tags.listData({
              *   limit: 50
              * });
+             * tags.forEach(tag => console.log(tag.title, tag.alias));
              *
-             * tags.forEach(tag => {
-             *   console.log(`${tag.title} (${tag.hits} hits)`);
+             * // Use caching for reference data (recommended)
+             * const cachedTags = await api.joomla.tags.list({
+             *   edgeCache: 5,  // Cache for 5 hours - tags are reference data
+             *   limit: 100
              * });
              * ```
              */
             list: this.createListMethod('/tags', TagListParamsSchema, TagListResponseSchema),
+            /**
+             * Get tags (data only)
+             * @description Returns only the data array from tags response
+             * @param params Optional filtering, search, and caching parameters
+             * @returns Array of tags (data only)
+             * @throws ValidationError When parameters are invalid or response is malformed
+             */
+            listData: async (params) => {
+                const response = await this.tags.list(params);
+                return response.data;
+            },
         };
         /**
          * Menu endpoints
@@ -448,6 +806,17 @@ export class JoomlaClient extends BaseServiceClient {
                     responseSchema: ContentDocumentResponseSchema,
                 }, undefined, { id: menuId });
             },
+            /**
+             * Get menu documentation (data only)
+             * @description Returns only the data from enhanced menu item document response
+             * @param menuId Menu item ID (string)
+             * @returns Menu document (data only)
+             * @throws ValidationError When response is malformed
+             */
+            getDocData: async (menuId) => {
+                const response = await this.menu.getDoc(menuId);
+                return response.data;
+            },
         };
         /**
          * Check service health (no bearer token required)