@simpleapps-com/augur-api 0.1.0

package/dist/esm/services/joomla/client.d.ts

@@ -0,0 +1,588 @@
+import { BaseServiceClient } from '../../core/base-client';
+import type { HTTPClient } from '../../core/client';
+import { ContentGetParams, ContentResponse, DocumentResponse, UserGroupListParams, UserGroupListResponse, UserGroupMembershipResponse, UserGroupDetailResponse, VerifyPasswordRequest, VerifyPasswordResponse, TrinityDocParams, TrinityDocResponse, UserGroupMappingRequest, UserGroupMappingResponse } 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 declare 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: HTTPClient, baseUrl?: string);
+    /**
+     * Content endpoints
+     * @description Methods for content management including articles, documents, and metadata
+     */
+    content: {
+        /**
+         * Retrieve a paginated list of content items
+         * @description Returns all content with optional filtering, pagination, and edge caching
+         * @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
+         * @throws ValidationError When parameters are invalid or response is malformed
+         * @example
+         * ```typescript
+         * // Get all content
+         * const content = await client.content.list();
+         *
+         * // Get filtered content
+         * const filtered = await client.content.list({
+         *   categoryIdList: '1,2,3',
+         *   limit: 20,
+         *   q: 'search term'
+         * });
+         *
+         * // Get content with 4-hour edge caching
+         * const cached = await client.content.list({
+         *   edgeCache: 4,  // Cache for 4 hours
+         *   categoryIdList: '1,2,3',
+         *   limit: 20
+         * });
+         * ```
+         */
+        list: (params?: {
+            edgeCache?: 3 | 2 | 4 | 1 | 5 | 8 | undefined;
+            limit?: number | undefined;
+            offset?: number | undefined;
+            q?: string | undefined;
+            orderBy?: string | undefined;
+            categoryIdList?: string | undefined;
+            tagsList?: string | undefined;
+        } | undefined) => Promise<{
+            data: {
+                id: number;
+                title: string;
+                alias: string;
+                catid: number;
+                created: string;
+                modified: string;
+                state?: number | undefined;
+                introtext?: string | undefined;
+                fulltext?: string | undefined;
+                ordering?: number | undefined;
+                images?: {
+                    image_intro?: string | undefined;
+                    image_fulltext?: string | undefined;
+                    float_intro?: string | undefined;
+                    float_fulltext?: string | undefined;
+                } | undefined;
+                hits?: number | undefined;
+                metadata?: unknown;
+            }[];
+            status: number;
+            options?: Record<string, unknown>[] | undefined;
+            message?: string | undefined;
+            totalResults?: number | undefined;
+            count?: number | undefined;
+        }>;
+        /**
+         * 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)
+         * @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
+         * @throws ValidationError When parameters are invalid or response is malformed
+         * @example
+         * ```typescript
+         * // Get by ID
+         * const content = await client.content.get(123);
+         *
+         * // Get by alias
+         * const content = await client.content.get(0, { alias: 'my-article', catid: 45 });
+         *
+         * // Get with 8-hour edge caching
+         * const cachedContent = await client.content.get(123, { edgeCache: 8 });
+         * ```
+         */
+        get: (contentId: number | string, params?: ContentGetParams) => Promise<ContentResponse>;
+        /**
+         * 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: (id: string | number, params?: unknown) => Promise<{
+            data: {
+                id: string;
+                title: string;
+                content: string;
+                metadata?: unknown;
+            };
+            status: number;
+            options?: Record<string, unknown>[] | undefined;
+            message?: string | undefined;
+            totalResults?: number | undefined;
+            count?: number | undefined;
+        }>;
+    };
+    /**
+     * User endpoints
+     * @description Methods for user management including authentication, CRUD operations, and group management
+     */
+    users: {
+        /**
+         * Retrieve a paginated list of users
+         * @description Returns all users with optional filtering, pagination, and edge caching
+         * @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
+         * @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}`);
+         *
+         * // Search users
+         * const searchResults = await client.users.list({ q: 'admin', limit: 5 });
+         *
+         * // Get users with 2-hour edge caching
+         * const cachedUsers = await client.users.list({
+         *   edgeCache: 2,  // Cache for 2 hours
+         *   limit: 20
+         * });
+         * ```
+         */
+        list: (params?: {
+            edgeCache?: 3 | 2 | 4 | 1 | 5 | 8 | undefined;
+            limit?: number | undefined;
+            offset?: number | undefined;
+            q?: string | undefined;
+            orderBy?: string | undefined;
+        } | undefined) => Promise<{
+            data: {
+                id: number;
+                username: string;
+                email: string;
+                name: string;
+                registerDate: string;
+                lastvisitDate: string;
+                lastResetTime?: string | undefined;
+                activation?: string | undefined;
+                block?: number | undefined;
+                timezone?: string | undefined;
+                language?: string | undefined;
+                customerId?: string | undefined;
+                contactId?: string | undefined;
+                profileValues?: Record<string, string> | undefined;
+            }[];
+            status: number;
+            options?: Record<string, unknown>[] | undefined;
+            message?: string | undefined;
+            totalResults?: number | undefined;
+            count?: number | undefined;
+        }>;
+        /**
+         * Get user details by ID
+         * @description Returns detailed information for a specific user with optional edge caching
+         * @param userId User ID (number or string)
+         * @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
+         * @example
+         * ```typescript
+         * const user = await client.users.get(123);
+         * console.log(user.username, user.email, user.registerDate);
+         *
+         * // Get with 1-hour edge caching
+         * const cachedUser = await client.users.get(123, { edgeCache: 1 });
+         * ```
+         */
+        get: (id: string | number, params?: import("../../core/base-client").CacheParams | undefined) => Promise<{
+            data: {
+                id: number;
+                username: string;
+                email: string;
+                name: string;
+                registerDate: string;
+                lastvisitDate: string;
+                lastResetTime?: string | undefined;
+                activation?: string | undefined;
+                block?: number | undefined;
+                timezone?: string | undefined;
+                language?: string | undefined;
+                customerId?: string | undefined;
+                contactId?: string | undefined;
+                profileValues?: Record<string, string> | undefined;
+            };
+            status: number;
+            options?: Record<string, unknown>[] | undefined;
+            message?: string | undefined;
+            totalResults?: number | undefined;
+            count?: number | undefined;
+        }>;
+        /**
+         * 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.id, userDoc.title, userDoc.content);
+         * ```
+         */
+        getDoc: (userId: number | string) => Promise<DocumentResponse>;
+        /**
+         * 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: (userId: number | string, params?: TrinityDocParams) => Promise<TrinityDocResponse>;
+        /**
+         * User groups sub-endpoints
+         * @description Methods for managing user group memberships and relationships
+         */
+        groups: {
+            /**
+             * Get user's groups
+             * @description Returns all groups that a specific user belongs to
+             * @param userId User ID (string)
+             * @param params Optional pagination parameters
+             * @returns Array of user group memberships
+             * @throws ValidationError When response is malformed
+             * @example
+             * ```typescript
+             * const groups = await client.users.groups.list('123');
+             * groups.forEach(group => console.log(group.title, group.groupId));
+             * ```
+             */
+            list: (userId: string, params?: {
+                limit?: number;
+                offset?: number;
+            }) => Promise<UserGroupMembershipResponse>;
+            /**
+             * 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: (userId: string, groupId: number | string) => Promise<UserGroupDetailResponse>;
+            /**
+             * 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: (userId: number | string, request: UserGroupMappingRequest) => Promise<UserGroupMappingResponse>;
+        };
+        /**
+         * 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
+         *
+         * @example
+         * // Standard authentication
+         * await client.users.verifyPassword({ username: 'user', password: 'pass' });
+         *
+         * // Cross-site authentication (when using augur_info as x-site-id header)
+         * await client.users.verifyPassword({
+         *   username: 'user',
+         *   password: 'pass',
+         *   siteId: 'customer_site_1'
+         * });
+         */
+        verifyPassword: (request: VerifyPasswordRequest) => Promise<VerifyPasswordResponse>;
+        /**
+         * Create a new user
+         * @description Creates a new user account in the system
+         * @param request User creation request data including username, email, name, and password
+         * @returns Created user information with ID, username, and email
+         * @throws ValidationError When request is invalid or response is malformed
+         * @example
+         * ```typescript
+         * const newUser = await client.users.create({
+         *   username: 'newuser',
+         *   email: 'user@example.com',
+         *   name: 'New User',
+         *   password: 'SecurePass123!'
+         * });
+         * console.log('Created user:', newUser.id, newUser.username);
+         * ```
+         */
+        create: (data: {
+            username: string;
+            email: string;
+            name: string;
+            password: string;
+        }) => Promise<{
+            data: {
+                id: number;
+                username: string;
+                email: string;
+            };
+            status: number;
+            options?: Record<string, unknown>[] | undefined;
+            message?: string | undefined;
+            totalResults?: number | undefined;
+            count?: number | undefined;
+        }>;
+        /**
+         * 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: (id: string | number, data: {
+            username?: string | undefined;
+            email?: string | undefined;
+            name?: string | undefined;
+            block?: number | undefined;
+            password?: string | undefined;
+        }) => Promise<{
+            data: {
+                id: number;
+                username: string;
+                email: string;
+                name: string;
+                registerDate: string;
+                lastvisitDate: string;
+                lastResetTime?: string | undefined;
+                activation?: string | undefined;
+                block?: number | undefined;
+                timezone?: string | undefined;
+                language?: string | undefined;
+                customerId?: string | undefined;
+                contactId?: string | undefined;
+                profileValues?: Record<string, string> | undefined;
+            };
+            status: number;
+            options?: Record<string, unknown>[] | undefined;
+            message?: string | undefined;
+            totalResults?: number | undefined;
+            count?: number | undefined;
+        }>;
+        /**
+         * 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: (id: string | number) => Promise<{
+            data: boolean;
+            status: number;
+            options?: Record<string, unknown>[] | undefined;
+            message?: string | undefined;
+            totalResults?: number | undefined;
+            count?: number | undefined;
+        }>;
+    };
+    /**
+     * User Groups endpoints
+     * @description Methods for managing system-wide user groups and their hierarchy
+     */
+    userGroups: {
+        /**
+         * Get user groups
+         * @description Returns hierarchical list of user groups with optional filtering, ordering, and edge caching
+         * @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
+         * @throws ValidationError When parameters are invalid or response is malformed
+         * @example
+         * ```typescript
+         * // Get all user groups
+         * const groups = await client.userGroups.list();
+         *
+         * // Get filtered groups
+         * const filtered = await client.userGroups.list({
+         *   orderBy: 'title|DESC',
+         *   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'
+         * });
+         *
+         * groups.forEach(group => {
+         *   console.log(`${group.title} (Level: ${group.level})`);
+         * });
+         * ```
+         */
+        list: (params?: UserGroupListParams) => Promise<UserGroupListResponse>;
+    };
+    /**
+     * Tags endpoints
+     * @description Methods for managing content tags and their hierarchical relationships
+     */
+    tags: {
+        /**
+         * Get tags
+         * @description Returns hierarchical list of content tags with optional filtering, search, and edge caching
+         * @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
+         * @throws ValidationError When parameters are invalid or response is malformed
+         * @example
+         * ```typescript
+         * // Get all tags
+         * const tags = await client.tags.list();
+         *
+         * // Search tags
+         * const searchTags = await client.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
+         *   limit: 50
+         * });
+         *
+         * tags.forEach(tag => {
+         *   console.log(`${tag.title} (${tag.hits} hits)`);
+         * });
+         * ```
+         */
+        list: (params?: {
+            edgeCache?: 3 | 2 | 4 | 1 | 5 | 8 | undefined;
+            limit?: number | undefined;
+            offset?: number | undefined;
+            q?: string | undefined;
+            catId?: number | undefined;
+            parentId?: number | undefined;
+        } | undefined) => Promise<{
+            data: {
+                path: string;
+                id: string;
+                title: string;
+                alias: string;
+                hits: number;
+                parent_id: string;
+                level: number;
+            }[];
+            status: number;
+            options?: Record<string, unknown>[] | undefined;
+            message?: string | undefined;
+            totalResults?: number | undefined;
+            count?: number | undefined;
+        }>;
+    };
+    /**
+     * Menu endpoints
+     * @description Methods for accessing menu structure and navigation documentation
+     */
+    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: (menuId: string) => Promise<DocumentResponse>;
+    };
+    /**
+     * 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);
+     * ```
+     */
+    getHealthCheck: () => Promise<{
+        data: {
+            siteHash: string;
+            siteId: string;
+        };
+        status: number;
+        options?: Record<string, unknown>[] | undefined;
+        message?: string | undefined;
+        totalResults?: number | undefined;
+        count?: number | undefined;
+    }>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/esm/services/joomla/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/services/joomla/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAGL,gBAAgB,EAEhB,eAAe,EAEf,gBAAgB,EAKhB,mBAAmB,EAEnB,qBAAqB,EAErB,2BAA2B,EAE3B,uBAAuB,EAKvB,qBAAqB,EAErB,sBAAsB,EAEtB,gBAAgB,EAEhB,kBAAkB,EAOlB,uBAAuB,EAEvB,wBAAwB,EAEzB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,YAAa,SAAQ,iBAAiB;IACjD;;;;OAIG;gBACS,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,MAAuC;IAI9E;;;OAGG;IACH,OAAO;QACL;;;;;;;;;;;;;;;;;;;;;;;;;;WA0BG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAGH;;;;;;;;;;;;;;;;;;;WAmBG;yBAEU,MAAM,GAAG,MAAM,WACjB,gBAAgB,KACxB,OAAO,CAAC,eAAe,CAAC;QAa3B;;;;;;;;;;;WAWG;;;;;;;;;;;;;;MAEH;IAEF;;;OAGG;IACH,KAAK;QACH;;;;;;;;;;;;;;;;;;;;;;WAsBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAGH;;;;;;;;;;;;;;;;WAgBG;;;;;;;;;;;;;;;;;;;;;;;;QAGH;;;;;;;;;;;WAWG;yBACoB,MAAM,GAAG,MAAM,KAAG,OAAO,CAAC,gBAAgB,CAAC;QAYlE;;;;;;;;;;;;;;;WAeG;gCAEO,MAAM,GAAG,MAAM,WACd,gBAAgB,KACxB,OAAO,CAAC,kBAAkB,CAAC;QAa9B;;;WAGG;;YAED;;;;;;;;;;;;eAYG;2BAEO,MAAM,WACL;gBAAE,KAAK,CAAC,EAAE,MAAM,CAAC;gBAAC,MAAM,CAAC,EAAE,MAAM,CAAA;aAAE,KAC3C,OAAO,CAAC,2BAA2B,CAAC;YAYvC;;;;;;;;;;;;eAYG;0BACiB,MAAM,WAAW,MAAM,GAAG,MAAM,KAAG,OAAO,CAAC,uBAAuB,CAAC;YAYvF;;;;;;;;;;;;eAYG;oCAEO,MAAM,GAAG,MAAM,WACd,uBAAuB,KAC/B,OAAO,CAAC,wBAAwB,CAAC;;QActC;;;;;;;;;;;;;;;;;;;;;;WAsBG;kCAC6B,qBAAqB,KAAG,OAAO,CAAC,sBAAsB,CAAC;QAYvF;;;;;;;;;;;;;;;;WAgBG;;;;;;;;;;;;;;;;;;QAGH;;;;;;;;;;;;;;;;WAgBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAOH;;;;;;;;;;;;;WAaG;;;;;;;;;MAEH;IAEF;;;OAGG;IACH,UAAU;QACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA4BG;wBACmB,mBAAmB,KAAG,OAAO,CAAC,qBAAqB,CAAC;MAW1E;IAEF;;;OAGG;IACH,IAAI;QACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA6BG;;;;;;;;;;;;;;;;;;;;;;;;MAEH;IAEF;;;OAGG;IACH,IAAI;QACF;;;;;;;;;;;;WAYG;yBACoB,MAAM,KAAG,OAAO,CAAC,gBAAgB,CAAC;MAWzD;IAEF;;;;;;;;;;;;OAYG;IACH,cAAc;;;;;;;;;;OAA2D;CAC1E"}