@titus-system/syncdesk 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+### Dev Notes
+
+---
+
+# 0.5.0 - 2026-04-04
+
+### Added
+
+- Get a specific client's conversations.

package/README.md

@@ -14,6 +14,8 @@ npm install @titus-system/syncdesk
 
 ### Install locally
 
+Alternatively, you can install locally bypassing the npm registry.
+
 ```sh
 npm run build
 npm pack
@@ -25,13 +27,44 @@ It creates a compressed tarball file in your folder. You can install it in your
 npm install /path/to/your/library-1.0.0.tgz
 ```
 
+### Configure your project to use the library
+
+This lib requires some configuration to work properly, such as the API base URL.
+To do so, you should call the `configLibrary` function in your project, passing the necessary configuration options. For example:
+
+```ts
+import { configLibrary } from "@titus-system/syncdesk";
+configureLibrary({
+  baseURL: 'http://localhost:8000/api', // should not be hardcoded, but in a .env file or similar
+
+  getAccessToken: () => localStorage.getItem('access_token'),
+  getRefreshToken: () => localStorage.getItem('refresh_token'),
+
+  onTokensRefreshed: (newAccess: string, newRefresh: string) => {
+    localStorage.setItem('access_token', newAccess)
+    localStorage.setItem('refresh_token', newRefresh)
+  },
+
+  onUnauthorized: () => {
+    localStorage.removeItem('access_token')
+    localStorage.removeItem('refresh_token')
+    window.location.href = '/login'
+
+    // // Mobile-specific logic to clear secure storage and navigate
+    // await SecureStore.deleteItemAsync('access_token')
+    // router.replace('/login')
+  }
+})
+```
+
 ## Publish new version to npm registry
 
 ```sh
 # You may have to login to npm registry first with `npm login`
 npm login
 
-npm run build && npm publish
+npm run build
+npm publish --access public
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titus-system/syncdesk",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "",
   "keywords": [],
   "author": "",

package/src/auth/hooks/useAuth.ts

@@ -1,17 +1,24 @@
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
 import { apiClient, ApiResponse } from "../../api";
 import {
+  AdminRegisterUserRequest,
+  ChangePasswordRequest,
+  ForgotPasswordRequest,
+  ForgotPasswordResponse,
   LoginResponse,
   RegisterUserRequest,
+  ResetPasswordRequest,
   UserCreatedResponse,
   UserLoginRequest,
   UserWithRoles,
 } from "../types/auth";
+import { User } from "../../users/types/user";
 
 const PATH = "auth";
 
 /**
  * Get the currently authenticated user's profile.
+ * @returns {UseQueryResult<UserWithRoles, Error>} The query result.
  */
 export const useGetMe = () => {
   return useQuery({
@@ -32,6 +39,8 @@ export const useGetMe = () => {
  * Log in a user.
  *
  * Refresh tokens are handled automatically using Interceptors.
+ * @param {UserLoginRequest} credentials The user login credentials.
+ * @returns {UseMutationResult<LoginResponse, Error, UserLoginRequest>} The mutation result.
  */
 export const useLogin = () => {
   const queryClient = useQueryClient();
@@ -55,6 +64,8 @@ export const useLogin = () => {
 
 /**
  * Register a new user.
+ * @param {RegisterUserRequest} userData The user registration details.
+ * @returns {UseMutationResult<UserCreatedResponse, Error, RegisterUserRequest>} The mutation result.
  */
 export const useRegister = () => {
   const queryClient = useQueryClient();
@@ -78,6 +89,7 @@ export const useRegister = () => {
 
 /**
  * Log out the current user.
+ * @returns {UseMutationResult<void, Error, void>} The mutation result.
  */
 export const useLogout = () => {
   const queryClient = useQueryClient();
@@ -93,3 +105,69 @@ export const useLogout = () => {
     },
   });
 };
+
+/**
+ * Register a new user as admin.
+ * @param {AdminRegisterUserRequest} userData The admin user registration details.
+ * @returns {UseMutationResult<User, Error, AdminRegisterUserRequest>} The mutation result.
+ */
+export const useAdminRegister = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (userData: AdminRegisterUserRequest): Promise<User> => {
+      const response = await apiClient.post<ApiResponse<User>>(
+        `${PATH}/admin/register`,
+        userData,
+      );
+      return response.data.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["users"] });
+    },
+  });
+};
+
+/**
+ * Change the current user's password.
+ * @param {ChangePasswordRequest} data The password change request details.
+ * @returns {UseMutationResult<void, Error, ChangePasswordRequest>} The mutation result.
+ */
+export const useChangePassword = () => {
+  return useMutation({
+    mutationFn: async (data: ChangePasswordRequest): Promise<void> => {
+      await apiClient.post(`${PATH}/change-password`, data);
+    },
+  });
+};
+
+/**
+ * Request a password reset.
+ * @param {ForgotPasswordRequest} data The forgot password request details.
+ * @returns {UseMutationResult<ForgotPasswordResponse, Error, ForgotPasswordRequest>} The mutation result.
+ */
+export const useForgotPassword = () => {
+  return useMutation({
+    mutationFn: async (
+      data: ForgotPasswordRequest,
+    ): Promise<ForgotPasswordResponse> => {
+      const response = await apiClient.post<
+        ApiResponse<ForgotPasswordResponse>
+      >(`${PATH}/forgot-password`, data);
+      return response.data.data;
+    },
+  });
+};
+
+/**
+ * Reset the current user's password using a valid reset token.
+ * @param {ResetPasswordRequest} data The reset password request details.
+ * @returns {UseMutationResult<void, Error, ResetPasswordRequest>} The mutation result.
+ */
+export const useResetPassword = () => {
+  return useMutation({
+    mutationFn: async (data: ResetPasswordRequest): Promise<void> => {
+      await apiClient.post(`${PATH}/reset-password`, data);
+    },
+  });
+};

package/src/auth/types/auth.ts

@@ -3,6 +3,8 @@ export type OAuthProvider = "local" | "google" | "microsoft";
 export interface LoginResponse {
   access_token: string;
   refresh_token: string;
+  must_change_password?: boolean;
+  must_accept_terms?: boolean;
 }
 
 export interface UserCreatedResponse {
@@ -20,11 +22,35 @@ export interface UserLoginRequest {
 
 export interface RegisterUserRequest {
   email: string;
-  name: string;
-  username: string;
+  name?: string;
+  username?: string;
   password: string;
 }
 
+export interface AdminRegisterUserRequest {
+  email: string;
+  name?: string | null;
+  role_ids?: number[];
+}
+
+export interface ChangePasswordRequest {
+  current_password: string;
+  new_password: string;
+}
+
+export interface ForgotPasswordRequest {
+  email: string;
+}
+
+export interface ResetPasswordRequest {
+  token: string;
+  new_password: string;
+}
+
+export interface ForgotPasswordResponse {
+  message: string;
+}
+
 // I am making a safe assumption for your /me route based on "user_with_roles"
 export interface UserWithRoles {
   id: string;

package/src/health/hooks/useHealth.ts

@@ -6,14 +6,19 @@ import type {
   ReadyResponse,
 } from "../types/health";
 
+const PATH = "";
+
 /**
  * Ping the server to check for basic connectivity.
+ * @returns {UseQueryResult<PingResponse, Error>} The result.
  */
 export const usePing = () => {
   return useQuery({
     queryKey: ["health", "ping"],
     queryFn: async (): Promise<PingResponse> => {
-      const response = await apiClient.get<ApiResponse<PingResponse>>("/ping");
+      const response = await apiClient.get<ApiResponse<PingResponse>>(
+        `${PATH}/ping`,
+      );
       return response.data.data;
     },
   });
@@ -21,13 +26,15 @@ export const usePing = () => {
 
 /**
  * Check the detailed health of the server and its dependencies (e.g. databases).
+ * @returns {UseQueryResult<HealthResponse, Error>} The result.
  */
 export const useHealth = () => {
   return useQuery({
     queryKey: ["health", "status"],
     queryFn: async (): Promise<HealthResponse> => {
-      const response =
-        await apiClient.get<ApiResponse<HealthResponse>>("/health");
+      const response = await apiClient.get<ApiResponse<HealthResponse>>(
+        `${PATH}/health`,
+      );
       return response.data.data;
     },
   });
@@ -35,13 +42,15 @@ export const useHealth = () => {
 
 /**
  * Check if the server is ready to accept traffic.
+ * @returns {UseQueryResult<ReadyResponse, Error>} The result.
  */
 export const useReady = () => {
   return useQuery({
     queryKey: ["health", "ready"],
     queryFn: async (): Promise<ReadyResponse> => {
-      const response =
-        await apiClient.get<ApiResponse<ReadyResponse>>("/ready");
+      const response = await apiClient.get<ApiResponse<ReadyResponse>>(
+        `${PATH}/ready`,
+      );
       return response.data.data;
     },
   });

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./roles";
 export * from "./permissions";
 export * from "./live_chat";
 export * from "./health";
+export * from "./ticket";
 
 export { config } from "./config";
 export type { LibraryConfig } from "./config";

package/src/live_chat/hooks/useLiveChat.ts

@@ -9,8 +9,9 @@ import {
 const PATH = "/conversations";
 
 /**
- * Get all conversations recursively mapping to a ticket.
- * @param ticket_id
+ * Get all conversations of a ticket.
+ * @param {string} ticket_id ticket_id parameter.
+ * @returns {UseQueryResult<Conversation[]>} The query result.
  */
 export const useGetConversations = (ticket_id: string) => {
   return useQuery({
@@ -26,10 +27,29 @@ export const useGetConversations = (ticket_id: string) => {
 };
 
 /**
- * Get paginated messages for a ticket.
- * @param ticket_id
- * @param page
- * @param limit
+ * Get a specific client's conversations.
+ * @param {string} client_id client_id parameter.
+ * @returns {UseQueryResult<Conversation[]>} The query result.
+ */
+export const useGetClientConversations = (client_id: string) => {
+  return useQuery({
+    queryKey: ["conversations", "client", client_id],
+    queryFn: async (): Promise<Conversation[]> => {
+      const response = await apiClient.get<ApiResponse<Conversation[]>>(
+        `${PATH}/client/${client_id}`,
+      );
+      return response.data.data;
+    },
+    enabled: !!client_id,
+  });
+};
+
+/**
+ * Get ticket messages with pagination.
+ * @param {string} ticket_id ticket_id parameter.
+ * @param {number} page page parameter.
+ * @param {number} limit limit parameter.
+ * @returns {UseQueryResult<PaginatedMessages>} The query result.
  */
 export const useGetPaginatedMessages = (
   ticket_id: string,
@@ -56,7 +76,9 @@ export const useGetPaginatedMessages = (
 };
 
 /**
- * Create a new conversation mapping to a ticket.
+ * Create a new conversation.
+ * @param {CreateConversationDTO} dto The conversation creation details.
+ * @returns {UseMutationResult<Conversation, Error, CreateConversationDTO>} The mutation result.
  */
 export const useCreateConversation = () => {
   const queryClient = useQueryClient();
@@ -79,6 +101,8 @@ export const useCreateConversation = () => {
 
 /**
  * Assign an agent to a conversation.
+ * @param {{ chat_id: string; agent_id: string }} params The chat ID and agent ID payload.
+ * @returns {UseMutationResult<void, Error, { chat_id: string; agent_id: string }>} The mutation result.
  */
 export const useSetConversationAgent = () => {
   const queryClient = useQueryClient();
@@ -93,9 +117,6 @@ export const useSetConversationAgent = () => {
     }): Promise<void> => {
       await apiClient.patch(`${PATH}/${chat_id}/set-agent/${agent_id}`);
     },
-    // We invalidate the ticket conversations here.
-    // To do so effectively, you may need the ticket_id, but the mutation only receives the chat_id.
-    // If ticket list invalidation is required, invalidate the whole 'conversations' key.
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ["conversations"] });
     },

package/src/permissions/hooks/usePermissions.ts

@@ -9,23 +9,35 @@ import type {
   AddPermissionRolesDTO,
 } from "../types/permission";
 
+const PATH = "/permissions";
+
+/**
+ * List all permissions.
+ * @returns {UseQueryResult<Permission[]>} The query result.
+ */
 export function usePermissions() {
   return useQuery<Permission[]>({
     queryKey: ["permissions"],
     queryFn: async () => {
-      const response =
-        await apiClient.get<ApiResponse<Permission[]>>("/permissions/");
+      const response = await apiClient.get<ApiResponse<Permission[]>>(
+        `${PATH}/`,
+      );
       return response.data.data;
     },
   });
 }
 
+/**
+ * Get a permission by ID.
+ * @param {number} id id parameter.
+ * @returns {UseQueryResult<Permission>} The query result.
+ */
 export function usePermission(id: number) {
   return useQuery<Permission>({
     queryKey: ["permissions", id],
     queryFn: async () => {
       const response = await apiClient.get<ApiResponse<Permission>>(
-        `/permissions/${id}`,
+        `${PATH}/${id}`,
       );
       return response.data.data;
     },
@@ -33,12 +45,17 @@ export function usePermission(id: number) {
   });
 }
 
+/**
+ * Create a new permission.
+ * @param {CreatePermissionDTO} dto DTO containing details.
+ * @returns {UseMutationResult<Permission, Error, CreatePermissionDTO>} The mutation result.
+ */
 export function useCreatePermission() {
   const queryClient = useQueryClient();
   return useMutation<Permission, Error, CreatePermissionDTO>({
     mutationFn: async (dto) => {
       const response = await apiClient.post<ApiResponse<Permission>>(
-        "/permissions/",
+        `${PATH}/`,
         dto,
       );
       return response.data.data;
@@ -49,6 +66,14 @@ export function useCreatePermission() {
   });
 }
 
+/**
+ * Replace a permission by ID.
+ * @param {number} id ID.
+ * @param {ReplacePermissionDTO} dto DTO containing details.
+ * @returns {UseMutationResult<Permission,
+    Error,
+    { id: number; dto: ReplacePermissionDTO }>} The mutation result.
+ */
 export function useReplacePermission() {
   const queryClient = useQueryClient();
   return useMutation<
@@ -58,7 +83,7 @@ export function useReplacePermission() {
   >({
     mutationFn: async ({ id, dto }) => {
       const response = await apiClient.put<ApiResponse<Permission>>(
-        `/permissions/${id}`,
+        `${PATH}/${id}`,
         dto,
       );
       return response.data.data;
@@ -70,6 +95,14 @@ export function useReplacePermission() {
   });
 }
 
+/**
+ * Update a permission by ID.
+ * @param {number} id ID.
+ * @param {UpdatePermissionDTO} dto DTO containing details.
+ * @returns {UseMutationResult<Permission,
+    Error,
+    { id: number; dto: UpdatePermissionDTO }>} The mutation result.
+ */
 export function useUpdatePermission() {
   const queryClient = useQueryClient();
   return useMutation<
@@ -79,7 +112,7 @@ export function useUpdatePermission() {
   >({
     mutationFn: async ({ id, dto }) => {
       const response = await apiClient.patch<ApiResponse<Permission>>(
-        `/permissions/${id}`,
+        `${PATH}/${id}`,
         dto,
       );
       return response.data.data;
@@ -91,12 +124,17 @@ export function useUpdatePermission() {
   });
 }
 
+/**
+ * Delete a permission by ID.
+ * @param {number} dto DTO containing details.
+ * @returns {UseMutationResult<Permission, Error, number>} The mutation result.
+ */
 export function useDeletePermission() {
   const queryClient = useQueryClient();
   return useMutation<Permission, Error, number>({
     mutationFn: async (id) => {
       const response = await apiClient.delete<ApiResponse<Permission>>(
-        `/permissions/${id}`,
+        `${PATH}/${id}`,
       );
       return response.data.data;
     },
@@ -107,12 +145,21 @@ export function useDeletePermission() {
   });
 }
 
+/**
+ * Get permission with associated roles.
+ *
+ * All roles that have this permission will be included in the
+ * response under a `roles` field.
+ *
+ * @param {number} id id parameter.
+ * @returns {UseQueryResult<Permission>} The query result.
+ */
 export function usePermissionRoles(id: number) {
   return useQuery<Permission>({
     queryKey: ["permissions", id, "roles"],
     queryFn: async () => {
       const response = await apiClient.get<ApiResponse<Permission>>(
-        `/permissions/${id}/roles`,
+        `${PATH}/${id}/roles`,
       );
       return response.data.data;
     },
@@ -120,6 +167,14 @@ export function usePermissionRoles(id: number) {
   });
 }
 
+/**
+ * Add a permission to a list of roles.
+ * @param {number} id ID.
+ * @param {AddPermissionRolesDTO} dto DTO containing details.
+ * @returns {UseMutationResult<Permission,
+    Error,
+    { id: number; dto: AddPermissionRolesDTO }>} The mutation result.
+ */
 export function useAddPermissionRoles() {
   const queryClient = useQueryClient();
   return useMutation<
@@ -129,7 +184,7 @@ export function useAddPermissionRoles() {
   >({
     mutationFn: async ({ id, dto }) => {
       const response = await apiClient.post<ApiResponse<Permission>>(
-        `/permissions/${id}/roles`,
+        `${PATH}/${id}/roles`,
         dto,
       );
       return response.data.data;

package/src/roles/hooks/useRoles.ts

@@ -1,33 +1,55 @@
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
 import { apiClient, ApiResponse } from "../../api";
-import type { Role, CreateRoleDTO, ReplaceRoleDTO, UpdateRoleDTO, AddRolePermissionsDTO } from "../types/role";
+import type {
+  Role,
+  CreateRoleDTO,
+  ReplaceRoleDTO,
+  UpdateRoleDTO,
+  AddRolePermissionsDTO,
+} from "../types/role";
 
+const PATH = "/roles";
+
+/**
+ * List all roles.
+ * @returns {UseQueryResult<Role[]>} The query result.
+ */
 export function useRoles() {
   return useQuery<Role[]>({
     queryKey: ["roles"],
     queryFn: async () => {
-      const response = await apiClient.get<ApiResponse<Role[]>>("/roles/");
+      const response = await apiClient.get<ApiResponse<Role[]>>(`${PATH}/`);
       return response.data.data;
     },
   });
 }
 
+/**
+ * Get a role by ID.
+ * @param {number} id id parameter.
+ * @returns {UseQueryResult<Role>} The query result.
+ */
 export function useRole(id: number) {
   return useQuery<Role>({
     queryKey: ["roles", id],
     queryFn: async () => {
-      const response = await apiClient.get<ApiResponse<Role>>(`/roles/${id}`);
+      const response = await apiClient.get<ApiResponse<Role>>(`${PATH}/${id}`);
       return response.data.data;
     },
     enabled: !!id,
   });
 }
 
+/**
+ * Create a new role.
+ * @param {CreateRoleDTO} dto DTO containing details.
+ * @returns {UseMutationResult<Role, Error, CreateRoleDTO>} The mutation result.
+ */
 export function useCreateRole() {
   const queryClient = useQueryClient();
   return useMutation<Role, Error, CreateRoleDTO>({
     mutationFn: async (dto) => {
-      const response = await apiClient.post<ApiResponse<Role>>("/roles/", dto);
+      const response = await apiClient.post<ApiResponse<Role>>(`${PATH}/`, dto);
       return response.data.data;
     },
     onSuccess: () => {
@@ -36,11 +58,20 @@ export function useCreateRole() {
   });
 }
 
+/**
+ * Replace a role by ID.
+ * @param {number} id ID.
+ * @param {ReplaceRoleDTO} dto DTO containing details.
+ * @returns {UseMutationResult<Role, Error, { id: number; dto: ReplaceRoleDTO }>} The mutation result.
+ */
 export function useReplaceRole() {
   const queryClient = useQueryClient();
   return useMutation<Role, Error, { id: number; dto: ReplaceRoleDTO }>({
     mutationFn: async ({ id, dto }) => {
-      const response = await apiClient.put<ApiResponse<Role>>(`/roles/${id}`, dto);
+      const response = await apiClient.put<ApiResponse<Role>>(
+        `${PATH}/${id}`,
+        dto,
+      );
       return response.data.data;
     },
     onSuccess: (_, { id }) => {
@@ -50,11 +81,20 @@ export function useReplaceRole() {
   });
 }
 
+/**
+ * Update a role by ID.
+ * @param {number} id ID.
+ * @param {UpdateRoleDTO} dto DTO containing details.
+ * @returns {UseMutationResult<Role, Error, { id: number; dto: UpdateRoleDTO }>} The mutation result.
+ */
 export function useUpdateRole() {
   const queryClient = useQueryClient();
   return useMutation<Role, Error, { id: number; dto: UpdateRoleDTO }>({
     mutationFn: async ({ id, dto }) => {
-      const response = await apiClient.patch<ApiResponse<Role>>(`/roles/${id}`, dto);
+      const response = await apiClient.patch<ApiResponse<Role>>(
+        `${PATH}/${id}`,
+        dto,
+      );
       return response.data.data;
     },
     onSuccess: (_, { id }) => {
@@ -64,11 +104,18 @@ export function useUpdateRole() {
   });
 }
 
+/**
+ * Delete a role by ID.
+ * @param {number} dto DTO containing details.
+ * @returns {UseMutationResult<Role, Error, number>} The mutation result.
+ */
 export function useDeleteRole() {
   const queryClient = useQueryClient();
   return useMutation<Role, Error, number>({
     mutationFn: async (id) => {
-      const response = await apiClient.delete<ApiResponse<Role>>(`/roles/${id}`);
+      const response = await apiClient.delete<ApiResponse<Role>>(
+        `${PATH}/${id}`,
+      );
       return response.data.data;
     },
     onSuccess: (_, id) => {
@@ -78,22 +125,39 @@ export function useDeleteRole() {
   });
 }
 
+/**
+ * Get the permissions for a role by ID.
+ * @param {number} id id parameter.
+ * @returns {UseQueryResult<Role>} The query result.
+ */
 export function useRolePermissions(id: number) {
   return useQuery<Role>({
     queryKey: ["roles", id, "permissions"],
     queryFn: async () => {
-      const response = await apiClient.get<ApiResponse<Role>>(`/roles/${id}/permissions`);
+      const response = await apiClient.get<ApiResponse<Role>>(
+        `${PATH}/${id}/permissions`,
+      );
       return response.data.data;
     },
     enabled: !!id,
   });
 }
 
+/**
+ * Add permissions to a role.
+ *
+ * @param {number} id ID.
+ * @param {AddRolePermissionsDTO} dto DTO containing details.
+ * @returns {UseMutationResult<Role, Error, { id: number; dto: AddRolePermissionsDTO }>} The mutation result.
+ */
 export function useAddRolePermissions() {
   const queryClient = useQueryClient();
   return useMutation<Role, Error, { id: number; dto: AddRolePermissionsDTO }>({
     mutationFn: async ({ id, dto }) => {
-      const response = await apiClient.post<ApiResponse<Role>>(`/roles/${id}/permissions`, dto);
+      const response = await apiClient.post<ApiResponse<Role>>(
+        `${PATH}/${id}/permissions`,
+        dto,
+      );
       return response.data.data;
     },
     onSuccess: (_, { id }) => {

package/src/ticket/hooks/useTickets.ts

@@ -0,0 +1,89 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { apiClient, ApiResponse } from "../../api";
+import {
+  CreateTicketRequest,
+  CreateTicketResponse,
+  TicketResponse,
+  TicketSearchFilters,
+  UpdateTicketStatusRequest,
+  UpdateTicketStatusResponse,
+} from "../types/ticket";
+
+const PATH = "/tickets";
+
+// Query keys
+export const TICKET_KEYS = {
+  all: ["tickets"] as const,
+  list: (filters: TicketSearchFilters) =>
+    [...TICKET_KEYS.all, "list", filters] as const,
+};
+
+/**
+ * Get all tickets.
+ * @param {TicketSearchFilters} filters filters parameter.
+ * @returns {UseQueryResult<TicketResponse[]>} The query result.
+ */
+export const useTickets = (filters: TicketSearchFilters = {}) => {
+  return useQuery({
+    queryKey: TICKET_KEYS.list(filters),
+    queryFn: async (): Promise<TicketResponse[]> => {
+      const response = await apiClient.get<ApiResponse<TicketResponse[]>>(
+        `${PATH}/`,
+        { params: filters },
+      );
+      return response.data.data;
+    },
+  });
+};
+
+/**
+ * Create a new ticket.
+ * @param {CreateTicketRequest} payload The ticket creation details.
+ * @returns {UseMutationResult<CreateTicketResponse, Error, CreateTicketRequest>} The mutation result.
+ */
+export const useCreateTicket = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (
+      payload: CreateTicketRequest,
+    ): Promise<CreateTicketResponse> => {
+      const response = await apiClient.post<ApiResponse<CreateTicketResponse>>(
+        `${PATH}/`,
+        payload,
+      );
+      return response.data.data;
+    },
+    onSuccess: () => {
+      // Invalidate tickets list queries on success
+      queryClient.invalidateQueries({ queryKey: TICKET_KEYS.all });
+    },
+  });
+};
+
+/**
+ * Update a ticket's status.
+ * @param {{ ticketId: string; payload: UpdateTicketStatusRequest }} params The ticket ID and status update payload.
+ * @returns {UseMutationResult<UpdateTicketStatusResponse, Error, { ticketId: string; payload: UpdateTicketStatusRequest }>} The mutation result.
+ */
+export const useUpdateTicketStatus = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      ticketId,
+      payload,
+    }: {
+      ticketId: string;
+      payload: UpdateTicketStatusRequest;
+    }): Promise<UpdateTicketStatusResponse> => {
+      const response = await apiClient.patch<
+        ApiResponse<UpdateTicketStatusResponse>
+      >(`${PATH}/${ticketId}/status`, payload);
+      return response.data.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: TICKET_KEYS.all });
+    },
+  });
+};

package/src/ticket/index.ts

@@ -0,0 +1,2 @@
+export * from "./types/ticket";
+export * from "./hooks/useTickets";

package/src/ticket/types/ticket.ts

@@ -0,0 +1,88 @@
+export type TicketType = "issue" | "access" | "new_feature";
+export type TicketCriticality = "high" | "medium" | "low";
+export type TicketStatus =
+  | "open"
+  | "in_progress"
+  | "waiting_for_provider"
+  | "waiting_for_validation"
+  | "finished";
+
+export interface CreateTicketRequest {
+  triage_id: string; // PydanticObjectId as string
+  type: TicketType;
+  criticality: TicketCriticality;
+  product: string;
+  description: string;
+  chat_ids: string[]; // List of PydanticObjectId as string
+  client_id: string; // UUID as string
+}
+
+export interface CreateTicketResponse {
+  id: string;
+  status: TicketStatus;
+  creation_date: string; // ISO datetime
+}
+
+export interface TicketSearchFilters {
+  ticket_id?: string;
+  client_id?: string;
+  triage_id?: string;
+  status?: TicketStatus;
+  criticality?: TicketCriticality;
+  type?: TicketType;
+  product?: string;
+}
+
+export interface TicketCompanyResponse {
+  id: string;
+  name: string;
+}
+
+export interface TicketClientResponse {
+  id: string;
+  name: string;
+  email: string;
+  company: TicketCompanyResponse;
+}
+
+export interface TicketHistoryResponse {
+  agent_id: string;
+  name: string;
+  level: string;
+  assignment_date: string;
+  exit_date: string;
+  transfer_reason: string;
+}
+
+export interface TicketCommentResponse {
+  comment_id: string;
+  author: string;
+  text: string;
+  date: string;
+  internal: boolean;
+}
+
+export interface TicketResponse {
+  id: string;
+  triage_id: string;
+  type: TicketType;
+  criticality: TicketCriticality;
+  product: string;
+  status: TicketStatus;
+  creation_date: string;
+  description: string;
+  chat_ids: string[];
+  agent_history: TicketHistoryResponse[];
+  client: TicketClientResponse;
+  comments: TicketCommentResponse[];
+}
+
+export interface UpdateTicketStatusRequest {
+  status: TicketStatus;
+}
+
+export interface UpdateTicketStatusResponse {
+  id: string;
+  previous_status: TicketStatus;
+  current_status: TicketStatus;
+}

package/src/users/hooks/useUsers.ts

@@ -12,7 +12,7 @@ const PATH = "/users";
 
 /**
  * Get all users.
- * @returns
+ * @returns {UseQueryResult<User[]>} The query result.
  */
 export const useGetUsers = () => {
   return useQuery({
@@ -28,8 +28,8 @@ export const useGetUsers = () => {
 
 /**
  * Get one user.
- * @param id
- * @returns
+ * @param {string} id id parameter.
+ * @returns {UseQueryResult<User>} The query result.
  */
 export const useGetUser = (id: string) => {
   return useQuery({
@@ -44,7 +44,8 @@ export const useGetUser = (id: string) => {
 
 /**
  * Create a user.
- * @returns
+ * @param {CreateUserDTO} user The user creation details.
+ * @returns {UseMutationResult<User, Error, CreateUserDTO>} The mutation result.
  */
 export const useCreateUser = () => {
   const queryClient = useQueryClient();
@@ -63,7 +64,8 @@ export const useCreateUser = () => {
 
 /**
  * Replace an entire user.
- * @returns
+ * @param {{ id: string; data: ReplaceUserDTO }} params The ID and user replacement data.
+ * @returns {UseMutationResult<User, Error, { id: string; data: ReplaceUserDTO }>} The mutation result.
  */
 export const useUpdateUser = () => {
   const queryClient = useQueryClient();
@@ -91,7 +93,8 @@ export const useUpdateUser = () => {
 
 /**
  * Update specific fields of a user.
- * @returns
+ * @param {{ id: string; data: UpdateUserDTO }} params The ID and user update data.
+ * @returns {UseMutationResult<User, Error, { id: string; data: UpdateUserDTO }>} The mutation result.
  */
 export const usePatchUser = () => {
   const queryClient = useQueryClient();
@@ -119,7 +122,8 @@ export const usePatchUser = () => {
 
 /**
  * Add roles to a user.
- * @returns
+ * @param {{ id: string; data: AddUserRolesDTO }} params The ID and user roles data.
+ * @returns {UseMutationResult<User, Error, { id: string; data: AddUserRolesDTO }>} The mutation result.
  */
 export const useAddUserRoles = () => {
   const queryClient = useQueryClient();

package/src/users/index.ts

@@ -14,9 +14,3 @@ export type {
   ReplaceUserDTO,
   AddUserRolesDTO,
 } from "./types/user";
-
-// # syncdesk-api/app/api/api_router
-// - /auth/ -- /app/domains/auth/routers/auth_router
-// | `/api/users/`             | User management (CRUD)       |
-// | `/api/roles/`             | Role management (CRUD)       |
-// | `/api/permissions/`       | Permission management (CRUD) |