@cabysis/candy-client

HTTP Client

Make HTTP Requests in a pretty easy way! Configure all your microservices endpoints in different modules and send requests!

Usage

You can use this library after installation as this example:

import { CandyClient, CandyClientOptions } from "./client";

// Example static function to retrieve a JWT token
// This function simulates retrieving a token for authorization purposes.
function getToken(): string {
  return "generic-jwt-token"; // Replace with actual logic to retrieve JWT token dynamically.
}

// Shared configuration options for CandyClient
// These options are applied to all client instances by default.
const sharedOptions: CandyClientOptions = {
  baseUrl: "http://localhost:8080/", // Base URL for the API endpoints
  headers: {
    Accept: "application/json", // Indicate that JSON is expected in responses
    "Content-Type": "application/json", // Specify that JSON is sent in requests
    "Access-Control-Allow-Origin": "*", // Allow cross-origin requests (CORS)
  },
  getToken: getToken, // Reference to the function that retrieves the JWT token
};

// Representation of a User entity
// Defines the structure of user data expected from the API.
class User {
  id: number; // Unique identifier for the user
  name: string; // Name of the user
  email: string; // Email address of the user
}

// Example client class for interacting with the authentication service
// Extends the generic CandyClient to include specific auth-related methods.
class AuthClient extends CandyClient {
  constructor() {
    super(sharedOptions); // Initialize the client with shared configuration options
  }

  // Method to sign in a user using email and password
  // Sends a POST request to the /auth/sign-in endpoint.
  async signIn(email: string, password: string): Promise<void> {
    return this.post<void>("/auth/sign-in", { email, password });
  }

  // Method to retrieve a list of all users
  // Sends a GET request to the /auth/users endpoint and returns a list of User objects.
  async getUsers(): Promise<User[]> {
    return this.get<User[]>("/auth/users");
  }

  // Method to retrieve credentials with custom headers
  // Sends a GET request to the /auth/credentials endpoint and overrides default headers.
  async getCredentials(): Promise<{ password: string; token: string }> {
    return this.get<{ password: string; token: string }>("/auth/credentials", {
      headers: {
        Authorization: "<Custom credential>", // Example of a custom Authorization header
        "Content-Type": "application/json",
      },
    });
  }

  // Method to upload a profile photo using multipart form data
  // Sends a POST request to the /auth/profile/photo endpoint with a file in FormData format.
  async uploadProfilePhoto(file: File): Promise<void> {
    const formData = new FormData();
    formData.append("file", file); // Append the file to the FormData object
    return this.post<void>("/auth/profile/photo", formData, {
      isMultipart: true, // Flag to indicate multipart form data is being used
    });
  }

  // Method to retrieve a profile photo as a Blob object
  // Sends a GET request to the /auth/profile/photo endpoint with Blob parsing enabled.
  async getProfilePhoto(): Promise<Blob> {
    return this.get<Blob>("/auth/profile/photo", {
      parseBlob: true, // Flag to parse the response as a Blob
    });
  }

  // Method to retrieve raw profile data as a Response object
  // Sends a GET request to the /auth/profile endpoint without parsing the response.
  async getProfileData(): Promise<Response> {
    return this.get<Response>("/auth/profile", {
      parseResponse: false, // Flag to return the raw response object
    });
  }
}

// Example use case for the sign-in request
// Demonstrates how to use the AuthClient to sign in a user.
async function signIn(email: string, password: string): Promise<void> {
  try {
    const authClient = new AuthClient(); // Create an instance of the AuthClient
    await authClient.signIn(email, password); // Attempt to sign in with the provided credentials
    console.log("Sign-in successful"); // Log success message if sign-in is successful
  } catch (error) {
    console.error("Sign-in failed:", error); // Log an error message if sign-in fails
  }
}