@zudello/modelcontextprotocol 1.0.0

package/dist/services/zudello/organization.js

@@ -0,0 +1,686 @@
+/**
+ * Zudello Organization Admin Services
+ *
+ * Organisation team, user, and user group management operations.
+ * Extracted from zudello.ts for modularity.
+ */
+import { logger } from "../../utils/logger.js";
+import { buildAuthenticationApiRequest } from "./core.js";
+// ============================================================================
+// Team Services
+// ============================================================================
+/**
+ * List all teams in the organisation
+ */
+export async function listOrgTeams(authContext, options = {}) {
+    try {
+        const { headers, apiBase, teamId } = await buildAuthenticationApiRequest(authContext);
+        const url = `${apiBase}/authentication/v1/resources/search?paginate=false&ignore_count=true`;
+        const body = {
+            model: "Team",
+            limit: options.limit || 1000,
+            select: [
+                "uuid", "name", "trading_name", "tax_number", "email", "phone",
+                "website", "logo", "team_type", "status", "disable_notifications",
+                "country__uuid", "country__name", "country__code",
+                "timezone__uuid", "timezone__code",
+                "currency__uuid", "currency__code", "currency__name", "currency__symbol",
+                "cluster__uuid", "cluster__name", "cluster__url",
+                "created_at", "updated_at", "deleted_at"
+            ],
+        };
+        logger.info("Zudello list org teams request", { url, teamId });
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello list org teams response received", {
+            httpStatus: response.status,
+            teamCount: data.data?.length || 0,
+        });
+        const teams = data.data || [];
+        const offset = options.offset || 0;
+        const limit = options.limit || 1000;
+        const paginatedTeams = teams.slice(offset, offset + limit);
+        return {
+            success: true,
+            data: {
+                teams: paginatedTeams,
+                metadata: {
+                    total: teams.length,
+                    returned: paginatedTeams.length,
+                    offset,
+                    limit,
+                }
+            }
+        };
+    }
+    catch (error) {
+        logger.error("Zudello list org teams error", {}, error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Fetch a single team by UUID
+ */
+export async function fetchOrgTeam(authContext, teamUuid) {
+    try {
+        const { headers, apiBase, teamId } = await buildAuthenticationApiRequest(authContext);
+        const params = new URLSearchParams({
+            model: "Team",
+            uuid: teamUuid,
+            team_uuid: teamId,
+            fetch_details: "true",
+            simplified: "true",
+        });
+        const url = `${apiBase}/authentication/v1/resources/?${params.toString()}`;
+        logger.info("Zudello fetch org team request", { url, teamUuid });
+        const response = await fetch(url, {
+            method: "GET",
+            headers,
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            if (response.status === 404) {
+                throw new Error(`Team not found: ${teamUuid}`);
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello fetch org team response received", {
+            httpStatus: response.status,
+            success: data.success,
+            model: data.model,
+        });
+        if (!data.success || !data.data) {
+            return { success: false, error: `Team not found: ${teamUuid}` };
+        }
+        return { success: true, data: data.data };
+    }
+    catch (error) {
+        logger.error("Zudello fetch org team error", { teamUuid }, error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Update team properties
+ */
+export async function updateOrgTeam(authContext, teamUuid, updates) {
+    try {
+        const { headers, apiBase, orgId } = await buildAuthenticationApiRequest(authContext);
+        const url = `${apiBase}/authentication/v1/resources/update_or_create`;
+        const body = {
+            simplified: false,
+            clear_nulls: false,
+            data: [{
+                    model: "Team",
+                    data: {
+                        uuid: teamUuid,
+                        organization_id: orgId,
+                        ...updates,
+                    },
+                    submit: false,
+                    enrich: false,
+                    extracted_event: false,
+                    update_status: false,
+                    update: true,
+                }],
+        };
+        logger.info("Zudello update org team request", {
+            url,
+            teamUuid,
+            updates: Object.keys(updates),
+        });
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello update org team response received", {
+            httpStatus: response.status,
+            status: data.status,
+            resourceCount: data.resources?.length || 0,
+        });
+        if (data.status !== "success" || !data.resources?.[0]?.success) {
+            const errorMsg = data.resources?.[0]?.message || data.message || "Failed to update team";
+            return { success: false, error: errorMsg };
+        }
+        return { success: true, data: data.resources[0].data };
+    }
+    catch (error) {
+        logger.error("Zudello update org team error", { teamUuid }, error);
+        return { success: false, error: error.message };
+    }
+}
+// ============================================================================
+// User Services
+// ============================================================================
+/**
+ * List all users in the organisation
+ */
+export async function listOrgUsers(authContext, options = {}) {
+    try {
+        const { headers, apiBase } = await buildAuthenticationApiRequest(authContext);
+        const url = `${apiBase}/authentication/v1/resources/search?paginate=false&ignore_count=true`;
+        const filter = { is_machine: false };
+        if (options.status) {
+            filter.status = options.status;
+        }
+        const body = {
+            model: "User",
+            select: [
+                "uuid", "first_name", "last_name", "email", "avatar", "status",
+                "is_machine", "zitadel_id", "created_at", "updated_at",
+                "teamuser__uuid", "teamuser__team", "teamuser__status",
+                "organizationuser__uuid", "organizationuser__is_admin", "organizationuser__status"
+            ],
+            filter,
+            order_by: ["first_name", "last_name"],
+            limit: options.limit || 100,
+        };
+        logger.info("Zudello list org users request", { url, filter });
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello list org users response received", {
+            httpStatus: response.status,
+            userCount: data.data?.length || 0,
+        });
+        let users = data.data || [];
+        // Apply client-side search filtering if provided
+        if (options.search) {
+            const searchTerm = options.search.toLowerCase();
+            users = users.filter((user) => user.first_name?.toLowerCase().includes(searchTerm) ||
+                user.last_name?.toLowerCase().includes(searchTerm) ||
+                user.email?.toLowerCase().includes(searchTerm));
+        }
+        const offset = options.offset || 0;
+        const limit = options.limit || 100;
+        const total = users.length;
+        const paginatedUsers = users.slice(offset, offset + limit);
+        return {
+            success: true,
+            data: {
+                users: paginatedUsers,
+                metadata: {
+                    total,
+                    returned: paginatedUsers.length,
+                    offset,
+                    limit,
+                }
+            }
+        };
+    }
+    catch (error) {
+        logger.error("Zudello list org users error", {}, error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Fetch a single user by UUID with full details
+ */
+export async function fetchOrgUser(authContext, userUuid) {
+    try {
+        const { headers, apiBase, teamId } = await buildAuthenticationApiRequest(authContext);
+        const params = new URLSearchParams({
+            model: "User",
+            uuid: userUuid,
+            team_uuid: teamId,
+            fetch_details: "true",
+            simplified: "true",
+        });
+        const url = `${apiBase}/authentication/v1/resources/?${params.toString()}`;
+        logger.info("Zudello fetch org user request", { url, userUuid });
+        const response = await fetch(url, {
+            method: "GET",
+            headers,
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            if (response.status === 404) {
+                throw new Error(`User not found: ${userUuid}`);
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello fetch org user response received", {
+            httpStatus: response.status,
+            success: data.success,
+            model: data.model,
+        });
+        if (!data.success || !data.data) {
+            return { success: false, error: `User not found: ${userUuid}` };
+        }
+        return { success: true, data: data.data };
+    }
+    catch (error) {
+        logger.error("Zudello fetch org user error", { userUuid }, error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Fetch TeamUser details for a specific user across all teams
+ */
+export async function fetchUserTeamAssignments(authContext, userUuid, orgId) {
+    try {
+        const { headers, apiBase } = await buildAuthenticationApiRequest(authContext);
+        const url = `${apiBase}/authentication/v1/resources/search?paginate=false&ignore_count=true`;
+        const body = {
+            model: "TeamUser",
+            filter: {
+                user_id: userUuid,
+                organization_id: orgId,
+            },
+            select: [
+                "uuid", "team", "user", "is_default", "status", "manager",
+                "groups__uuid", "default_location", "default_subsidiary",
+                "delegate_all", "delegate_duties", "delegate_to_user",
+                "delegate_start", "delegate_end"
+            ],
+            limit: 10000,
+        };
+        logger.info("Zudello fetch user team assignments request", { url, userUuid, orgId });
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello fetch user team assignments response received", {
+            httpStatus: response.status,
+            assignmentCount: data.data?.length || 0,
+        });
+        return { success: true, data: data.data || [] };
+    }
+    catch (error) {
+        logger.error("Zudello fetch user team assignments error", { userUuid }, error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Create a new user in the organisation
+ */
+export async function createOrgUser(authContext, userData) {
+    try {
+        const { headers, apiBase, orgId } = await buildAuthenticationApiRequest(authContext);
+        const url = `${apiBase}/authentication/v1/resources/update_or_create`;
+        const body = {
+            simplified: false,
+            clear_nulls: false,
+            data: [{
+                    model: "User",
+                    data: {
+                        first_name: userData.first_name,
+                        last_name: userData.last_name,
+                        email: userData.email,
+                        avatar: "",
+                        status: "ACTIVE",
+                        is_machine: false,
+                        organizations: {
+                            replace: true,
+                            items: [{
+                                    fetch: true,
+                                    model: "Organization",
+                                    data: { uuid: orgId },
+                                }],
+                        },
+                        teams: [],
+                        teamuser_set: [],
+                        organizationuser_set: [],
+                        primary_organization_id: orgId,
+                    },
+                    submit: false,
+                    enrich: false,
+                    extracted_event: false,
+                    update_status: false,
+                    create: true,
+                    extra_data: {
+                        is_email_verified: userData.is_email_verified ?? true,
+                        ...(userData.password && { new_password: userData.password }),
+                    },
+                }],
+        };
+        logger.info("Zudello create org user request", {
+            url,
+            email: userData.email,
+            firstName: userData.first_name,
+            lastName: userData.last_name,
+        });
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello create org user response received", {
+            httpStatus: response.status,
+            status: data.status,
+            resourceCount: data.resources?.length || 0,
+        });
+        if (data.status !== "success" || !data.resources?.[0]?.success) {
+            const errorMsg = data.resources?.[0]?.message || data.message || "Failed to create user";
+            return { success: false, error: errorMsg };
+        }
+        return { success: true, data: data.resources[0].data };
+    }
+    catch (error) {
+        logger.error("Zudello create org user error", { email: userData.email }, error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Update user profile (name only - email is read-only)
+ */
+export async function updateOrgUser(authContext, userUuid, updates) {
+    try {
+        const { headers, apiBase } = await buildAuthenticationApiRequest(authContext);
+        const url = `${apiBase}/authentication/v1/resources/update_or_create`;
+        const body = {
+            simplified: false,
+            clear_nulls: false,
+            data: [{
+                    model: "User",
+                    data: {
+                        uuid: userUuid,
+                        ...updates,
+                    },
+                    submit: false,
+                    enrich: false,
+                    extracted_event: false,
+                    update_status: false,
+                    update: true,
+                }],
+        };
+        logger.info("Zudello update org user request", {
+            url,
+            userUuid,
+            updates: Object.keys(updates),
+        });
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello update org user response received", {
+            httpStatus: response.status,
+            status: data.status,
+        });
+        if (data.status !== "success" || !data.resources?.[0]?.success) {
+            const errorMsg = data.resources?.[0]?.message || data.message || "Failed to update user";
+            return { success: false, error: errorMsg };
+        }
+        return { success: true, data: data.resources[0].data };
+    }
+    catch (error) {
+        logger.error("Zudello update org user error", { userUuid }, error);
+        return { success: false, error: error.message };
+    }
+}
+/**
+ * Create or update TeamUser assignment (assign user to team with groups)
+ */
+export async function assignUserToTeam(authContext, assignment) {
+    try {
+        const { headers, apiBase } = await buildAuthenticationApiRequest(authContext);
+        const url = `${apiBase}/authentication/v1/resources/update_or_create`;
+        const isUpdate = !!assignment.teamUserUuid;
+        const dataPayload = {
+            team_id: assignment.teamId,
+            user_id: assignment.userId,
+            organization_id: assignment.orgId,
+        };
+        if (assignment.teamUserUuid) {
+            dataPayload.uuid = assignment.teamUserUuid;
+        }
+        if (assignment.managerId !== undefined) {
+            dataPayload.manager_id = assignment.managerId;
+        }
+        if (assignment.isDefault !== undefined) {
+            dataPayload.is_default = assignment.isDefault;
+        }
+        if (assignment.status !== undefined) {
+            dataPayload.status = assignment.status;
+        }
+        if (assignment.defaultSubsidiary !== undefined) {
+            dataPayload.default_subsidiary = assignment.defaultSubsidiary;
+        }
+        if (assignment.defaultLocation !== undefined) {
+            dataPayload.default_location = assignment.defaultLocation;
+        }
+        if (assignment.delegateAll !== undefined) {
+            dataPayload.delegate_all = assignment.delegateAll;
+        }
+        if (assignment.delegateDuties !== undefined) {
+            dataPayload.delegate_duties = assignment.delegateDuties;
+        }
+        if (assignment.delegateToUserId !== undefined) {
+            dataPayload.delegate_to_user_id = assignment.delegateToUserId;
+        }
+        if (assignment.delegateStart !== undefined) {
+            dataPayload.delegate_start = assignment.delegateStart;
+        }
+        if (assignment.delegateEnd !== undefined) {
+            dataPayload.delegate_end = assignment.delegateEnd;
+        }
+        if (assignment.groups !== undefined) {
+            dataPayload.groups = {
+                replace: true,
+                items: assignment.groups.map(uuid => ({
+                    fetch: true,
+                    data: { uuid },
+                })),
+            };
+        }
+        const body = {
+            simplified: false,
+            clear_nulls: false,
+            data: [{
+                    model: "TeamUser",
+                    data: dataPayload,
+                    submit: false,
+                    enrich: false,
+                    extracted_event: false,
+                    update_status: false,
+                    create: !isUpdate,
+                    update: isUpdate,
+                }],
+        };
+        logger.info("Zudello assign user to team request", {
+            url,
+            teamId: assignment.teamId,
+            userId: assignment.userId,
+            isUpdate,
+            groupCount: assignment.groups?.length || 0,
+        });
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello assign user to team response received", {
+            httpStatus: response.status,
+            status: data.status,
+        });
+        if (data.status !== "success" || !data.resources?.[0]?.success) {
+            const errorMsg = data.resources?.[0]?.message || data.message || "Failed to assign user to team";
+            return { success: false, error: errorMsg };
+        }
+        return { success: true, data: data.resources[0].data };
+    }
+    catch (error) {
+        logger.error("Zudello assign user to team error", { assignment }, error);
+        return { success: false, error: error.message };
+    }
+}
+// ============================================================================
+// User Group Services
+// ============================================================================
+/**
+ * List all user groups in the organisation
+ */
+export async function listOrgUserGroups(authContext, options = {}) {
+    try {
+        const { headers, apiBase } = await buildAuthenticationApiRequest(authContext);
+        const url = `${apiBase}/authentication/v1/resources/search?paginate=false&ignore_count=true`;
+        const select = [
+            "uuid", "name", "description", "can_delegate", "status", "user_group_type"
+        ];
+        if (options.includeTeamUsers) {
+            select.push("team_users__uuid");
+        }
+        const body = {
+            model: "UserGroup",
+            select,
+            limit: options.limit || 100,
+            annotate: {
+                permissions_count: { function: "Count", field: "permissions" },
+            },
+        };
+        logger.info("Zudello list org user groups request", { url, options });
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("Authentication failed - invalid JWT token");
+            }
+            if (response.status === 403) {
+                throw new Error("Access forbidden - organisation admin or Zudello staff privileges required");
+            }
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Zudello API error: ${response.status} - ${errorText}`);
+        }
+        const data = await response.json();
+        logger.info("Zudello list org user groups response received", {
+            httpStatus: response.status,
+            userGroupCount: data.data?.length || 0,
+        });
+        let userGroups = data.data || [];
+        // Apply client-side filters
+        if (options.status) {
+            userGroups = userGroups.filter(group => group.status === options.status);
+        }
+        if (options.userGroupType) {
+            userGroups = userGroups.filter(group => group.user_group_type === options.userGroupType);
+        }
+        if (options.search) {
+            const searchTerm = options.search.toLowerCase();
+            userGroups = userGroups.filter(group => group.name?.toLowerCase().includes(searchTerm) ||
+                group.description?.toLowerCase().includes(searchTerm));
+        }
+        // Remove team_users if not requested (for performance)
+        if (!options.includeTeamUsers) {
+            userGroups = userGroups.map(group => ({
+                ...group,
+                team_users: undefined,
+            }));
+        }
+        const offset = options.offset || 0;
+        const limit = options.limit || 100;
+        const total = userGroups.length;
+        const paginatedGroups = userGroups.slice(offset, offset + limit);
+        return {
+            success: true,
+            data: {
+                userGroups: paginatedGroups,
+                metadata: {
+                    total,
+                    returned: paginatedGroups.length,
+                    offset,
+                    limit,
+                }
+            }
+        };
+    }
+    catch (error) {
+        logger.error("Zudello list org user groups error", {}, error);
+        return { success: false, error: error.message };
+    }
+}
+//# sourceMappingURL=organization.js.map