@titus-system/syncdesk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -19,3 +19,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 
 ### Dev Notes
+
+---
+
+# 0.5.0 - 2026-04-04
+
+### Added
+
+- Get a specific client's conversations.

package/README.md

@@ -27,6 +27,36 @@ 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

package/package.json

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

package/src/auth/hooks/useAuth.ts

@@ -18,6 +18,7 @@ const PATH = "auth";
 
 /**
  * Get the currently authenticated user's profile.
+ * @returns {UseQueryResult<UserWithRoles, Error>} The query result.
  */
 export const useGetMe = () => {
   return useQuery({
@@ -38,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();
@@ -61,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();
@@ -84,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();
@@ -102,6 +108,8 @@ 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();
@@ -121,7 +129,9 @@ export const useAdminRegister = () => {
 };
 
 /**
- * Change the password of the current user.
+ * 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({
@@ -132,7 +142,9 @@ export const useChangePassword = () => {
 };
 
 /**
- * Request a password reset email.
+ * 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({
@@ -148,7 +160,9 @@ export const useForgotPassword = () => {
 };
 
 /**
- * Reset a user's password using a valid reset token.
+ * 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({

package/src/health/hooks/useHealth.ts

@@ -10,6 +10,7 @@ const PATH = "";
 
 /**
  * Ping the server to check for basic connectivity.
+ * @returns {UseQueryResult<PingResponse, Error>} The result.
  */
 export const usePing = () => {
   return useQuery({
@@ -25,6 +26,7 @@ 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({
@@ -40,6 +42,7 @@ export const useHealth = () => {
 
 /**
  * Check if the server is ready to accept traffic.
+ * @returns {UseQueryResult<ReadyResponse, Error>} The result.
  */
 export const useReady = () => {
   return useQuery({

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

@@ -11,6 +11,10 @@ import type {
 
 const PATH = "/permissions";
 
+/**
+ * List all permissions.
+ * @returns {UseQueryResult<Permission[]>} The query result.
+ */
 export function usePermissions() {
   return useQuery<Permission[]>({
     queryKey: ["permissions"],
@@ -23,6 +27,11 @@ export function usePermissions() {
   });
 }
 
+/**
+ * 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],
@@ -36,6 +45,11 @@ 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>({
@@ -52,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<
@@ -73,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<
@@ -94,6 +124,11 @@ 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>({
@@ -110,6 +145,15 @@ 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"],
@@ -123,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<

package/src/roles/hooks/useRoles.ts

@@ -10,6 +10,10 @@ import type {
 
 const PATH = "/roles";
 
+/**
+ * List all roles.
+ * @returns {UseQueryResult<Role[]>} The query result.
+ */
 export function useRoles() {
   return useQuery<Role[]>({
     queryKey: ["roles"],
@@ -20,6 +24,11 @@ export function useRoles() {
   });
 }
 
+/**
+ * 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],
@@ -31,6 +40,11 @@ export function useRole(id: number) {
   });
 }
 
+/**
+ * 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>({
@@ -44,6 +58,12 @@ 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 }>({
@@ -61,6 +81,12 @@ 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 }>({
@@ -78,6 +104,11 @@ 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>({
@@ -94,6 +125,11 @@ 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"],
@@ -107,6 +143,13 @@ export function useRolePermissions(id: number) {
   });
 }
 
+/**
+ * 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 }>({

package/src/ticket/hooks/useTickets.ts

@@ -18,7 +18,11 @@ export const TICKET_KEYS = {
     [...TICKET_KEYS.all, "list", filters] as const,
 };
 
-/** Get all tickets. */
+/**
+ * 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),
@@ -32,7 +36,11 @@ export const useTickets = (filters: TicketSearchFilters = {}) => {
   });
 };
 
-/** Create a new ticket. */
+/**
+ * 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();
 
@@ -53,7 +61,11 @@ export const useCreateTicket = () => {
   });
 };
 
-/** Update a ticket's status. */
+/**
+ * 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();
 

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) |