@titus-system/syncdesk 0.3.1

package/.editorconfig

@@ -0,0 +1,53 @@
+# EditorConfig is awesome: http://EditorConfig.org
+# 1st version comes from a Gist by @avandrevitor [here](https://gist.github.com/avandrevitor/b917770334af3a43cf8c489f93287a84)
+#
+# Extended version is available in [WesleyGoncalves' GitHub Gist](https://gist.githubusercontent.com/WesleyGoncalves/ae64d95f663a15d8df455d1f0e5f7687)
+#
+# Be aware that:
+# > Comments should go in individual lines, **we are not sure whether appending comments may cause issues**.
+# Emphasis added. [link](https://github.com/editorconfig/editorconfig/wiki/Syntax)
+#
+#
+# You can download this file
+# directly to your project from the command-line
+# curl -O https://gist.githubusercontent.com/WesleyGoncalves/ae64d95f663a15d8df455d1f0e5f7687/raw/.editorconfig
+
+# top-most EditorConfig file
+root = true
+
+# All PHP files MUST use the Unix LF (linefeed) line ending.
+# Code MUST use an indent of 4 spaces, and MUST NOT use tabs for indenting.
+# All PHP files MUST end with a single blank line.
+# There MUST NOT be trailing whitespace at the end of non-blank lines.
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# PHP-Files | Python | Java
+[*.{php,py,java}]
+indent_style = space
+indent_size = 4
+
+[composer.json,docker-compose.yml]
+indent_style = space
+indent_size = 4
+
+# **NOT IMPLEMENTED BY editorConfig** PHP-Files. See [this for further information](https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties#ideas-for-domain-specific-properties)
+[*.php]
+curly_bracket_next_line = true
+indent_brace_style = K&R
+spaces_around_operators = true
+# block_comment_start = '/*'
+# block_comment_end = '*/'
+# line_comment = '//'
+
+# BLADE-Files | MD | HTML | LESS | SASS | CSS | JS | JSX | TS | TSX | JSON | ReST | YAML | TXT
+[*.{blade.php,md,html,less,sass,scss,css,js{x,},ts{x,},json,rst,y{a,}ml,txt}]
+indent_style = space
+indent_size = 2
+
+[{package.json}]
+indent_style = space
+indent_size = 2

package/.github/workflows/notify-main.yml

@@ -0,0 +1,17 @@
+name: Notify Main Repo
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Repository Dispatch
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.PAT_TOKEN }}
+          repository: Titus-System/SyncDesk
+          event-type: submodule_update

package/README.md

@@ -0,0 +1,41 @@
+# SyncDesk Library
+
+Biblioteca de integração do [SyncDesk](https://github.com/Titus-System/SyncDesk).
+
+Essa biblioteca fornece recursos para as aplicações frontend do sistema SyncDesk, permitindo a comunicação eficiente e segura entre os componentes do sistema. Ela inclui funcionalidades de autenticação, gerenciamento de requisições para o backend e manipulação de dados, facilitando a construção de interfaces de usuário responsivas e interativas.
+
+## Installation
+
+### Install from npm registry
+
+```sh
+npm install @titus-system/syncdesk
+```
+
+### Install locally
+
+```sh
+npm run build
+npm pack
+```
+
+It creates a compressed tarball file in your folder. You can install it in your project with:
+
+```sh
+npm install /path/to/your/library-1.0.0.tgz
+```
+
+## 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
+```
+
+---
+
+## Auth
+
+If the token expires, the auth module will automatically attempt to refresh it using the refresh token. If the refresh token is also expired or invalid, the `config.onUnauthorized` callback will be triggered, allowing you to handle the unauthorized state (e.g., redirecting to the login page).

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@titus-system/syncdesk",
+  "version": "0.3.1",
+  "description": "",
+  "keywords": [],
+  "author": "",
+  "license": "",
+  "bugs": {
+    "url": "https://github.com/Titus-System/syncdesk-library/issues"
+  },
+  "homepage": "https://github.com/Titus-System/syncdesk-library#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Titus-System/syncdesk-library.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "dev": "tsc --watch"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.95.2",
+    "react": "^19.2.4"
+  },
+  "dependencies": {
+    "axios": "^1.13.6",
+    "react-use-websocket": "^4.13.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^6.0.2"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,135 @@
+import axios, { InternalAxiosRequestConfig } from "axios";
+import { config, LibraryConfig } from "../config";
+
+export const apiClient = axios.create();
+
+/**
+ * Configure the library with user-provided settings.
+ */
+export const configureLibrary = (userConfig: LibraryConfig) => {
+  // Overwrite the default internal config with the user's settings
+  Object.assign(config, userConfig);
+
+  apiClient.defaults.baseURL = config.baseURL;
+  apiClient.defaults.timeout = config.timeout;
+};
+
+// INTERCEPTORS
+
+/**
+ * Request Interceptor.
+ * Automatically adds the access token to the Authorization header of every request if it's available.
+ */
+apiClient.interceptors.request.use(
+  async (reqConfig) => {
+    const token = await config.getAccessToken();
+    if (token && reqConfig.headers) {
+      reqConfig.headers.Authorization = `Bearer ${token}`;
+    }
+    return reqConfig;
+  },
+  (error) => Promise.reject(error),
+);
+
+/**
+ * Response Interceptor.
+ */
+let isRefreshing = false; // Flag to prevent multiple simultaneous refresh attempts
+let failedQueue: Array<{
+  // Queue to hold requests that come in while we're refreshing tokens
+  resolve: (token: string) => void;
+  reject: (error: any) => void;
+}> = [];
+/** Processes the queue of failed requests after token refresh. */
+const processQueue = (error: any, token: string | null = null) => {
+  failedQueue.forEach((promise) => {
+    if (error) {
+      promise.reject(error);
+    } else {
+      promise.resolve(token as string);
+    }
+  });
+  failedQueue = [];
+};
+
+/**
+ * This interceptor watches for 401 responses. If it sees one, it tries to get a new access token using
+ * the refresh token.
+ *
+ * Meanwhile, it queues up any new requests that also fail with 401, and once it gets a new token,
+ * it retries all the failed requests with the new token. If the refresh token is also expired/invalid,
+ * it calls the onUnauthorized callback to let the app know they need to log in again.
+ */
+apiClient.interceptors.response.use(
+  (response) => response, // success
+  async (error) => {
+    const originalRequest = error.config as InternalAxiosRequestConfig & {
+      _retry?: boolean;
+    };
+
+    // if 401 and not retried
+    if (error.response?.status === 401 && !originalRequest._retry) {
+      if (
+        originalRequest.url?.includes("/refresh") ||
+        originalRequest.url?.includes("/login")
+      ) {
+        config.onUnauthorized();
+        return Promise.reject(error);
+      }
+
+      // If another request is currently refreshing the token, pause this request and add to queue
+      if (isRefreshing) {
+        return (
+          new Promise((resolve, reject) => {
+            failedQueue.push({ resolve, reject });
+          })
+            .then((token) => {
+              // on success, add the new token to the request header and return the client
+              originalRequest.headers.Authorization = `Bearer ${token}`;
+              return apiClient(originalRequest);
+            })
+            // on error, reject the request
+            .catch((err) => Promise.reject(err))
+        );
+      }
+
+      // Mark that we are starting the refresh process
+      originalRequest._retry = true;
+      isRefreshing = true;
+
+      try {
+        const refreshToken = await config.getRefreshToken();
+
+        if (!refreshToken) {
+          throw new Error("No refresh token available.");
+        }
+
+        // Do a standard axios call to get the new token, so the interceptors are not called again.
+        const refreshResponse = await axios.post(`${config.baseURL}/refresh`, {
+          refresh_token: refreshToken,
+        });
+
+        const newAccessToken = refreshResponse.data.data.access_token;
+        const newRefreshToken = refreshResponse.data.data.refresh_token;
+
+        await config.onTokensRefreshed(newAccessToken, newRefreshToken);
+
+        // Resume all the other paused requests with the new token
+        processQueue(null, newAccessToken);
+
+        // Retry the original request that failed
+        originalRequest.headers.Authorization = `Bearer ${newAccessToken}`;
+        return apiClient(originalRequest);
+      } catch (refreshError) {
+        // If the refresh token is completely expired, kill the queue and log them out
+        processQueue(refreshError, null);
+        config.onUnauthorized();
+        return Promise.reject(refreshError);
+      } finally {
+        isRefreshing = false;
+      }
+    }
+
+    return Promise.reject(error);
+  },
+);

package/src/api/index.ts

@@ -0,0 +1,2 @@
+export { apiClient, configureLibrary } from "./client";
+export type { ApiResponse } from "./typings";

package/src/api/typings.ts

@@ -0,0 +1,3 @@
+export interface ApiResponse<T> {
+  data: T;
+}

package/src/auth/hooks/useAuth.ts

@@ -0,0 +1,95 @@
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { apiClient, ApiResponse } from "../../api";
+import {
+  LoginResponse,
+  RegisterUserRequest,
+  UserCreatedResponse,
+  UserLoginRequest,
+  UserWithRoles,
+} from "../types/auth";
+
+const PATH = "auth";
+
+/**
+ * Get the currently authenticated user's profile.
+ */
+export const useGetMe = () => {
+  return useQuery({
+    queryKey: ["me"],
+    queryFn: async (): Promise<UserWithRoles> => {
+      const response = await apiClient.get<ApiResponse<UserWithRoles>>(
+        `${PATH}/me`,
+      );
+
+      return response.data.data;
+    },
+    // if the user isn't logged in (401)
+    retry: false,
+  });
+};
+
+/**
+ * Log in a user.
+ *
+ * Refresh tokens are handled automatically using Interceptors.
+ */
+export const useLogin = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (
+      credentials: UserLoginRequest,
+    ): Promise<LoginResponse> => {
+      const response = await apiClient.post<ApiResponse<LoginResponse>>(
+        `${PATH}/login`,
+        credentials,
+      );
+      return response.data.data;
+    },
+    onSuccess: () => {
+      // After a successful login, fetch the new user's profile
+      queryClient.invalidateQueries({ queryKey: ["me"] });
+    },
+  });
+};
+
+/**
+ * Register a new user.
+ */
+export const useRegister = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (
+      userData: RegisterUserRequest,
+    ): Promise<UserCreatedResponse> => {
+      const response = await apiClient.post<ApiResponse<UserCreatedResponse>>(
+        `${PATH}/register`,
+        userData,
+      );
+      return response.data.data;
+    },
+    onSuccess: () => {
+      // Registration also logs them in (returns tokens), so fetch their profile
+      queryClient.invalidateQueries({ queryKey: ["me"] });
+    },
+  });
+};
+
+/**
+ * Log out the current user.
+ */
+export const useLogout = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (): Promise<void> => {
+      await apiClient.post(`${PATH}/logout`);
+    },
+    onSuccess: () => {
+      // clear cache
+      queryClient.setQueryData(["me"], null);
+      queryClient.clear();
+    },
+  });
+};

package/src/auth/index.ts

@@ -0,0 +1,12 @@
+export { useGetMe, useLogin, useRegister, useLogout } from "./hooks/useAuth";
+
+export type {
+  OAuthProvider,
+  LoginResponse,
+  UserCreatedResponse,
+  UserLoginRequest,
+  RegisterUserRequest,
+  UserWithRoles,
+} from "./types/auth";
+
+export type { Status, Session } from "./types/session";

package/src/auth/types/auth.ts

@@ -0,0 +1,35 @@
+export type OAuthProvider = "local" | "google" | "microsoft";
+
+export interface LoginResponse {
+  access_token: string;
+  refresh_token: string;
+}
+
+export interface UserCreatedResponse {
+  id: string;
+  email: string;
+  username: string;
+  access_token: string;
+  refresh_token: string;
+}
+
+export interface UserLoginRequest {
+  email: string;
+  password: string;
+}
+
+export interface RegisterUserRequest {
+  email: string;
+  name: string;
+  username: string;
+  password: string;
+}
+
+// I am making a safe assumption for your /me route based on "user_with_roles"
+export interface UserWithRoles {
+  id: string;
+  email: string;
+  username: string;
+  name?: string | null;
+  roles: string[];
+}

package/src/auth/types/session.ts

@@ -0,0 +1,12 @@
+export type Status = "active" | "expired" | "invalid" | "revoked";
+
+export interface Session {
+  id: string;
+  user_id: string;
+  refresh_token_hash: string;
+  status: Status;
+  device_info: Record<string, unknown>;
+  expires_at: Date | string;
+  last_used_at: Date | string;
+  revoked_at: Date | string;
+}

package/src/config.ts

@@ -0,0 +1,31 @@
+export interface LibraryConfig {
+  /** API URL */
+  baseURL: string;
+  timeout?: number;
+
+  /* Get current access token */
+  getAccessToken: () => string | null | Promise<string | null>;
+
+  /** Get the refresh token when it needs a new one */
+  getRefreshToken: () => string | null | Promise<string | null>;
+
+  /** Callback fired when the library successfully gets new tokens from the backend */
+  onTokensRefreshed: (
+    accessToken: string,
+    refreshToken: string,
+  ) => void | Promise<void>;
+
+  /** Fired if the user is not authenticated and refresh token fails. */
+  onUnauthorized: () => void;
+}
+
+export const config: Required<LibraryConfig> = {
+  baseURL: "",
+  timeout: 10000,
+  getAccessToken: () => null,
+  getRefreshToken: () => null,
+  onTokensRefreshed: () => {},
+  onUnauthorized: () => {
+    console.warn("Unauthorized error caught. No handler provided.");
+  },
+};

package/src/health/hooks/useHealth.ts

@@ -0,0 +1,48 @@
+import { useQuery } from "@tanstack/react-query";
+import { apiClient, ApiResponse } from "../../api";
+import type {
+  PingResponse,
+  HealthResponse,
+  ReadyResponse,
+} from "../types/health";
+
+/**
+ * Ping the server to check for basic connectivity.
+ */
+export const usePing = () => {
+  return useQuery({
+    queryKey: ["health", "ping"],
+    queryFn: async (): Promise<PingResponse> => {
+      const response = await apiClient.get<ApiResponse<PingResponse>>("/ping");
+      return response.data.data;
+    },
+  });
+};
+
+/**
+ * Check the detailed health of the server and its dependencies (e.g. databases).
+ */
+export const useHealth = () => {
+  return useQuery({
+    queryKey: ["health", "status"],
+    queryFn: async (): Promise<HealthResponse> => {
+      const response =
+        await apiClient.get<ApiResponse<HealthResponse>>("/health");
+      return response.data.data;
+    },
+  });
+};
+
+/**
+ * Check if the server is ready to accept traffic.
+ */
+export const useReady = () => {
+  return useQuery({
+    queryKey: ["health", "ready"],
+    queryFn: async (): Promise<ReadyResponse> => {
+      const response =
+        await apiClient.get<ApiResponse<ReadyResponse>>("/ready");
+      return response.data.data;
+    },
+  });
+};

package/src/health/index.ts

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

package/src/health/types/health.ts

@@ -0,0 +1,10 @@
+export interface PingResponse {
+  message: string;
+}
+
+export interface HealthResponse {
+  postgres_status: "connected" | "degraded";
+  mongo_status: "connected" | "degraded";
+}
+
+export interface ReadyResponse {}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./auth";
+export * from "./api";
+export * from "./users";
+export * from "./roles";
+export * from "./permissions";
+export * from "./live_chat";
+export * from "./health";
+
+export { config } from "./config";
+export type { LibraryConfig } from "./config";

package/src/live_chat/hooks/useLiveChat.ts

@@ -0,0 +1,103 @@
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { apiClient, ApiResponse } from "../../api";
+import {
+  Conversation,
+  CreateConversationDTO,
+  PaginatedMessages,
+} from "../types/live_chat";
+
+const PATH = "/conversations";
+
+/**
+ * Get all conversations recursively mapping to a ticket.
+ * @param ticket_id
+ */
+export const useGetConversations = (ticket_id: string) => {
+  return useQuery({
+    queryKey: ["conversations", "ticket", ticket_id],
+    queryFn: async (): Promise<Conversation[]> => {
+      const response = await apiClient.get<ApiResponse<Conversation[]>>(
+        `${PATH}/ticket/${ticket_id}`,
+      );
+      return response.data.data;
+    },
+    enabled: !!ticket_id,
+  });
+};
+
+/**
+ * Get paginated messages for a ticket.
+ * @param ticket_id
+ * @param page
+ * @param limit
+ */
+export const useGetPaginatedMessages = (
+  ticket_id: string,
+  page = 1,
+  limit = 10,
+) => {
+  return useQuery({
+    queryKey: [
+      "conversations",
+      "ticket",
+      ticket_id,
+      "messages",
+      { page, limit },
+    ],
+    queryFn: async (): Promise<PaginatedMessages> => {
+      const response = await apiClient.get<ApiResponse<PaginatedMessages>>(
+        `${PATH}/ticket/${ticket_id}/messages`,
+        { params: { page, limit } },
+      );
+      return response.data.data;
+    },
+    enabled: !!ticket_id,
+  });
+};
+
+/**
+ * Create a new conversation mapping to a ticket.
+ */
+export const useCreateConversation = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (dto: CreateConversationDTO): Promise<Conversation> => {
+      const response = await apiClient.post<ApiResponse<Conversation>>(
+        PATH,
+        dto,
+      );
+      return response.data.data;
+    },
+    onSuccess: (_, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: ["conversations", "ticket", variables.ticket_id],
+      });
+    },
+  });
+};
+
+/**
+ * Assign an agent to a conversation.
+ */
+export const useSetConversationAgent = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      chat_id,
+      agent_id,
+    }: {
+      chat_id: string;
+      agent_id: string;
+    }): 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"] });
+    },
+  });
+};