@simpleapps-com/augur-api
Version:
TypeScript client library for Augur microservices API endpoints
937 lines (936 loc) • 54.1 kB
JavaScript
import { BaseServiceClient } from '../../core/base-client';
import { ContentListParamsSchema, ContentListResponseSchema, ContentGetParamsSchema, ContentResponseSchema, ContentDocumentResponseSchema, UserListParamsSchema, UserListResponseSchema, UserResponseSchema, UserGroupListParamsSchema, UserGroupListResponseSchema, UserGroupMembershipParamsSchema, UserGroupMembershipResponseSchema, UserGroupDetailResponseSchema, TagListParamsSchema, TagListResponseSchema, HealthCheckResponseSchema, PingResponseSchema, VerifyPasswordRequestSchema, VerifyPasswordResponseSchema, TrinityDocParamsSchema, TrinityDocResponseSchema, CreateUserRequestSchema, CreateUserResponseSchema, UpdateUserRequestSchema, UpdateUserResponseSchema, BlockUserResponseSchema, UserGroupMappingRequestSchema, UserGroupMappingResponseSchema, UserDocumentResponseSchema, } from './schemas';
/**
* Joomla API Client
* @description Client for interacting with Joomla microservice API endpoints
* @example
* ```typescript
* import { HTTPClient } from '@augur/api-client/core';
* import { JoomlaClient } from '@augur/api-client/services/joomla';
*
* const http = new HTTPClient('joomla', { siteId: 'your-site-id', bearerToken: 'your-token' });
* const joomla = new JoomlaClient(http);
*
* // List content
* const content = await joomla.content.list({ limit: 10 });
*
* // Verify user password
* const auth = await joomla.users.verifyPassword({ username: 'user', password: 'pass' });
* ```
*/
export class JoomlaClient extends BaseServiceClient {
/**
* Create a new JoomlaClient instance
* @param http Configured HTTPClient instance
* @param baseUrl Base URL for the Joomla API (default: https://joomla.augur-api.com)
*/
constructor(http, baseUrl = 'https://joomla.augur-api.com') {
super('joomla', http, baseUrl);
/**
* Content endpoints
* @description Methods for content management including articles, documents, and metadata
*/
this.content = {
/**
* Retrieve a paginated list of content items
* @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.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 with full response metadata
* const response = await api.joomla.content.list();
* console.log(`Found ${response.total} articles, showing ${response.data.length}`);
*
* // Filter content by categories with search
* const filtered = await api.joomla.content.list({
* categoryIdList: '1,2,3',
* q: 'product review',
* limit: 10
* });
*
* // 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 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.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 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 just content data without metadata
* const article = await api.joomla.content.getData(123);
* console.log(article.title, article.introtext, article.fulltext);
*
* // Use edge caching for frequently accessed content
* const cachedContent = await api.joomla.content.get(123, { edgeCache: 8 });
* ```
*/
get: async (contentId, params) => {
return this.executeRequest({
method: 'GET',
path: '/content/{id}',
paramsSchema: ContentGetParamsSchema,
responseSchema: ContentResponseSchema,
}, params, { id: String(contentId) });
},
/**
* Get content documentation
* @description Returns enhanced content document with custom fields, images, and metadata
* @param contentId Content ID (number) or alias lookup (use 0 with query params)
* @returns Enhanced content document with additional metadata
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const doc = await client.content.getDoc(123);
* console.log(doc.id, doc.title, doc.content, doc.metadata);
* ```
*/
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
* @description Methods for user management including authentication, CRUD operations, and group management
*/
this.users = {
/**
* Retrieve a paginated list of users
* @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.q Search query for filtering users by username/email (optional)
* @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 without search filter
* 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 with specific query and pagination
* const searchResults = await api.joomla.users.list({
* q: 'simple',
* limit: 10,
* offset: 0
* });
*
* // 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: 50
* });
* ```
*/
list: this.createListMethod('/users', UserListParamsSchema, UserListResponseSchema),
/**
* Get user details by ID
* @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 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
* // 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);
*
* // Use edge caching for frequently accessed users
* const cachedUser = await api.joomla.users.get(123, { edgeCache: 1 });
* ```
*/
get: this.createGetMethod('/users/{id}', UserResponseSchema),
/**
* Get user documentation
* @description Returns enhanced user document with profile values, customer information, and metadata
* @param userId User ID (number or string)
* @returns Enhanced user document with profile data
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const userDoc = await client.users.getDoc(123);
* console.log(userDoc.username, userDoc.email, userDoc.customerId);
* console.log(userDoc.profileValues?.['simpleweb_customer.simpleweb_customer_companyname']);
* ```
*/
getDoc: async (userId) => {
return this.executeRequest({
method: 'GET',
path: '/users/{id}/doc',
responseSchema: UserDocumentResponseSchema,
}, undefined, { id: String(userId) });
},
/**
* Get Trinity user documentation
* @description Returns specialized Trinity business logic document with territory assignment and role detection
* @param userId User ID (number or string)
* @param params Optional filtering and pagination parameters
* @returns Trinity document with profile, role, groups, and territory information
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const trinity = await client.users.getTrinityDoc(123);
* console.log(trinity.profile.companyName, trinity.territory, trinity.role);
*
* // With filtering
* const filtered = await client.users.getTrinityDoc(123, { q: 'search', limit: 5 });
* ```
*/
getTrinityDoc: async (userId, params) => {
return this.executeRequest({
method: 'GET',
path: '/users/{id}/trinity',
paramsSchema: TrinityDocParamsSchema,
responseSchema: TrinityDocResponseSchema,
}, params, { id: String(userId) });
},
/**
* User groups sub-endpoints
* @description Methods for managing user group memberships and relationships
*/
groups: {
/**
* 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
* @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
* // 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));
* ```
*/
list: async (userId, params) => {
return this.executeRequest({
method: 'GET',
path: '/users/{id}/groups',
paramsSchema: UserGroupMembershipParamsSchema,
responseSchema: UserGroupMembershipResponseSchema,
}, params, { id: userId });
},
/**
* Get specific user group membership
* @description Returns detailed information about a user's membership in a specific group
* @param userId User ID (string)
* @param groupId Group ID (number or string)
* @returns User group membership details
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const membership = await client.users.groups.get('123', 1);
* console.log(membership.groupTitle, membership.memberSince);
* ```
*/
get: async (userId, groupId) => {
return this.executeRequest({
method: 'GET',
path: '/users/{id}/groups/{groupId}',
responseSchema: UserGroupDetailResponseSchema,
}, undefined, { id: userId, groupId: String(groupId) });
},
/**
* Create or update user group mapping
* @description Adds or updates a user's membership in a group
* @param userId User ID (number or string)
* @param request Group mapping request data
* @returns Created or updated group mapping information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const mapping = await client.users.groups.createMapping(123, { groupId: 5 });
* console.log(mapping.created ? 'Created' : 'Updated', 'group mapping');
* ```
*/
createMapping: async (userId, request) => {
return this.executeRequest({
method: 'POST',
path: '/users/{id}/groups',
paramsSchema: UserGroupMappingRequestSchema,
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 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
* ```typescript
* // Standard authentication with full response
* const response = await api.joomla.users.verifyPassword({
* username: 'johndoe',
* password: 'securePassword123'
* });
*
* 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({
method: 'POST',
path: '/users/verify-password',
paramsSchema: VerifyPasswordRequestSchema,
responseSchema: VerifyPasswordResponseSchema,
}, request);
},
/**
* 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
* @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
* // 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:', 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),
/**
* Update an existing user
* @description Updates user information for an existing user account
* @param userId User ID (number or string)
* @param request User update data with optional fields to modify
* @returns Updated user object with all current information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const updatedUser = await client.users.update(123, {
* email: 'newemail@example.com',
* name: 'Updated Name',
* block: 0 // Unblock user
* });
* console.log('Updated user:', updatedUser.username, updatedUser.email);
* ```
*/
update: this.createUpdateMethod('/users/{id}', UpdateUserRequestSchema, UpdateUserResponseSchema),
/**
* Block (deactivate) a user
* @description Blocks a user account without deleting it, preventing user access to the system
* @param userId User ID (number or string)
* @returns Boolean indicating successful blocking operation
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const blocked = await client.users.block(123);
* if (blocked) {
* console.log('User has been successfully blocked');
* }
* ```
*/
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
* @description Methods for managing system-wide user groups and their hierarchy
*/
this.userGroups = {
/**
* 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.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 with hierarchy information
* const response = await api.joomla.userGroups.list();
* response.data.forEach(group => {
* console.log(`${group.title} (Level: ${group.level}, Parent: ${group.parentId})`);
* });
*
* // Filter and order groups
* const ordered = await api.joomla.userGroups.list({
* orderBy: 'title|ASC',
* parentIdList: '1,2'
* });
*
* // Get just groups data without metadata
* const groups = await api.joomla.userGroups.listData({
* orderBy: 'level|ASC'
* });
*
* // 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'
* });
* ```
*/
list: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/usergroups',
paramsSchema: UserGroupListParamsSchema,
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
* @description Methods for managing content tags and their hierarchical relationships
*/
this.tags = {
/**
* 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.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 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 by keyword
* const searchTags = await api.joomla.tags.list({
* q: 'technology',
* catId: 1,
* limit: 10
* });
*
* // Get just tags data without metadata
* const tags = await api.joomla.tags.listData({
* limit: 50
* });
* tags.forEach(tag => console.log(tag.title, tag.alias));
*
* // 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
* @description Methods for accessing menu structure and navigation documentation
*/
this.menu = {
/**
* Get menu documentation
* @description Returns enhanced menu item document with navigation hierarchy information
* @param menuId Menu item ID (string)
* @returns Complete menu document with navigation structure
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const menuDoc = await client.menu.getDoc('101');
* console.log('Menu:', menuDoc.data.title, menuDoc.data.link);
* console.log('Level:', menuDoc.data.level, 'Parent:', menuDoc.data.parentId);
* ```
*/
getDoc: async (menuId) => {
return this.executeRequest({
method: 'GET',
path: '/menu/{id}/doc',
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)
* @description Monitor service availability without authentication overhead
* @returns Health check response with site information
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const health = await client.getHealthCheck();
* console.log('Service health:', health.status);
* console.log('Site ID:', health.data.siteId);
* console.log('Site Hash:', health.data.siteHash);
* ```
*/
this.getHealthCheck = this.createHealthCheckMethod(HealthCheckResponseSchema);
/**
* Ping test (no bearer token required)
* @description Simple connectivity test that returns 'pong'
* @returns Ping response containing 'pong' string
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const pingResult = await client.ping();
* console.log(pingResult); // 'pong'
* ```
*/
this.ping = this.createPingMethod(PingResponseSchema);
/**
* Health Data Operations
* @description Direct access to health check data without response metadata
*/
this.healthData = {
/**
* Get health check data without response metadata
* @returns Promise<unknown> Health status data directly
*/
check: async () => {
const response = await this.getHealthCheck();
return response.data;
},
/**
* Get ping data without response metadata
* @returns Promise<unknown> Ping response data directly
*/
ping: async () => {
const response = await this.ping();
return response.data;
},
};
}
/**
* Override getDiscoveryMetadata to provide hardcoded endpoint metadata
* This works around the JSDoc parsing issue in compiled JavaScript
*/
getDiscoveryMetadata() {
return {
serviceName: this.serviceName,
description: this.getServiceDescription(),
baseUrl: this.baseUrl,
endpoints: [
{
fullPath: 'api.joomla.users.list',
service: 'joomla',
domain: 'user-management',
method: 'GET',
path: '/users',
description: 'Retrieve a paginated list of users',
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'],
dataMethod: 'listData()',
discoverable: true,
},
{
fullPath: 'api.joomla.users.get',
service: 'joomla',
domain: 'user-management',
method: 'GET',
path: '/users/{id}',
description: 'Get user details by ID',
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'],
dataMethod: 'getData(userId, params)',
discoverable: true,
},
{
fullPath: 'api.joomla.users.verifyPassword',
service: 'joomla',
domain: 'authentication',
method: 'POST',
path: '/users/verify-password',
description: 'Verify user credentials and authenticate',
searchTerms: [
'verify password',
'authenticate',
'login',
'user authentication',
'credentials',
'sign in',
],
relatedEndpoints: [