@edraj/tsdmart 4.0.2 → 4.0.3

package/dmart.service.ts

@@ -29,10 +29,19 @@ import {
 export class Dmart {
     static axiosDmartInstance: AxiosInstance;
 
+    /**
+     * Sets the Axios instance to be used for all HTTP requests
+     * @param axiosInstance - The Axios instance to use for API calls
+     */
     static setAxiosInstance(axiosInstance: AxiosInstance) {
         Dmart.axiosDmartInstance = axiosInstance;
     }
 
+    /**
+     * Gets the current Axios instance
+     * @returns The configured Axios instance
+     * @throws Error if no Axios instance has been set
+     */
     public static getAxiosInstance(): AxiosInstance {
         if (!Dmart.axiosDmartInstance) {
             throw new Error("Axios instance is not set. Please set it using setAxiosInstance method.");
@@ -40,30 +49,60 @@ export class Dmart {
         return Dmart.axiosDmartInstance;
     }
 
+    /**
+     * Gets the current headers object used for API requests
+     * @returns The headers object containing request headers
+     */
     public static getHeaders() {
         return headers;
     }
 
+    /**
+     * Updates the headers object with new headers
+     * @param newHeaders - Object containing headers to merge with existing headers
+     */
     public static setHeaders(newHeaders: any) {
         Object.assign(headers, newHeaders);
     }
 
+    /**
+     * Gets the base URL from the Axios instance
+     * @returns The base URL string
+     */
     public static getBaseURL() {
         return Dmart.axiosDmartInstance.defaults.baseURL;
     }
 
+    /**
+     * Sets the base URL for the Axios instance
+     * @param url - The base URL to set
+     */
     public static set setBaseURL(url: string) {
         Dmart.axiosDmartInstance.defaults.baseURL = url;
     }
 
+    /**
+     * Gets the current authentication token
+     * @returns The token string without the "Bearer " prefix, or null if not set
+     */
     public static getToken() {
         return headers["Authorization"] ? headers["Authorization"].replace("Bearer ", "") : null;
     }
 
+    /**
+     * Sets the authentication token in the headers
+     * @param token - The JWT token to use for authentication
+     */
     public static setToken(token: string) {
         headers["Authorization"] = `Bearer ${token}`;
     }
 
+    /**
+     * Authenticates a user with shortname and password
+     * @param shortname - The user's shortname (username)
+     * @param password - The user's password
+     * @returns Promise resolving to LoginResponse containing authentication data and access token
+     */
     public static async login(shortname: string, password: string) {
         const response = await Dmart.axiosDmartInstance.post<LoginResponse>(
             `user/login`,
@@ -78,6 +117,13 @@ export class Dmart {
         return data;
     }
 
+    /**
+     * Authenticates a user with custom credentials and password
+     * @param credentials - Object containing login credentials (e.g., email, phone, etc.)
+     * @param password - The user's password
+     * @returns Promise resolving to LoginResponse containing authentication data and access token
+     * @throws Error if login request fails
+     */
     public static async loginBy(credentials: any, password: string) {
         try {
             const response = await Dmart.axiosDmartInstance.post<LoginResponse>(
@@ -96,6 +142,11 @@ export class Dmart {
         }
     }
 
+    /**
+     * Logs out the current user session
+     * @returns Promise resolving to ApiResponse indicating logout status
+     * @throws Error if logout request fails
+     */
     public static async logout() {
         try {
             const {data} = await Dmart.axiosDmartInstance.post<ApiResponse>(
@@ -109,6 +160,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Creates a new user account
+     * @param request - ActionRequestRecord containing user creation data
+     * @returns Promise resolving to ActionResponse with creation result
+     * @throws Error if user creation fails
+     */
     public static async createUser(request: ActionRequestRecord) {
         try {
             const {data} = await Dmart.axiosDmartInstance.post<ActionResponse>(
@@ -122,6 +179,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Updates an existing user's profile information
+     * @param request - ActionRequestRecord containing user update data
+     * @returns Promise resolving to ActionResponse with update result
+     * @throws Error if user update fails
+     */
     public static async updateUser(request: ActionRequestRecord) {
         try {
             const {data} = await Dmart.axiosDmartInstance.post<ActionResponse>(
@@ -135,6 +198,13 @@ export class Dmart {
         }
     }
 
+    /**
+     * Checks if a user property value already exists in the system
+     * @param prop - The property name to check (e.g., 'email', 'shortname')
+     * @param value - The value to check for existence
+     * @returns Promise resolving to ResponseEntry indicating if the value exists
+     * @throws Error if check request fails
+     */
     public static async checkExisting(prop: string, value: string) {
         try {
             const {data} = await Dmart.axiosDmartInstance.get<ResponseEntry>(
@@ -147,6 +217,11 @@ export class Dmart {
         }
     }
 
+    /**
+     * Retrieves the current user's profile information
+     * @returns Promise resolving to ProfileResponse containing user profile data, permissions, and roles
+     * @throws Error if profile retrieval fails
+     */
     public static async getProfile() {
         try {
             const {data} = await Dmart.axiosDmartInstance.get<ProfileResponse>(`user/profile`, {
@@ -168,6 +243,13 @@ export class Dmart {
         }
     }
 
+    /**
+     * Executes a query against the Dmart API to retrieve data
+     * @param query - QueryRequest object containing query parameters, filters, and sorting options
+     * @param scope - The scope for the query (default: DmartScope.managed)
+     * @returns Promise resolving to ApiQueryResponse with query results or null
+     * @throws Error if query execution fails
+     */
     public static async query(
         query: QueryRequest,
         scope: string = DmartScope.managed
@@ -189,6 +271,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Exports query results as CSV format
+     * @param query - Query object with parameters for CSV export
+     * @returns Promise resolving to ApiQueryResponse containing CSV data
+     * @throws Error if CSV generation fails
+     */
     public static async csv(query: any): Promise<ApiQueryResponse> {
         try {
             query.sort_type = query.sort_type || SortyType.ascending;
@@ -205,6 +293,11 @@ export class Dmart {
         }
     }
 
+    /**
+     * Creates resources from an uploaded CSV file
+     * @param request - ResourcesFromCSVRequest containing file data and resource configuration
+     * @returns Promise resolving to ApiResponse with creation results, or error object if failed
+     */
     public static async resourcesFromCsv(
         request: ResourcesFromCSVRequest
     ) {
@@ -232,7 +325,12 @@ export class Dmart {
         }
     }
 
-
+    /**
+     * Performs space-level operations (create, update, delete spaces)
+     * @param action - ActionRequest containing the operation details for space management
+     * @returns Promise resolving to ActionResponse with operation result
+     * @throws Error if space operation fails
+     */
     public static async space(action: ActionRequest): Promise<ActionResponse> {
         try {
             const {data} = await Dmart.axiosDmartInstance.post<ActionResponse>(
@@ -246,6 +344,11 @@ export class Dmart {
         }
     }
 
+    /**
+     * Executes a general request action against the Dmart API
+     * @param action - ActionRequest containing the request details and parameters
+     * @returns Promise resolving to ActionResponse with request result
+     */
     public static async request(action: ActionRequest): Promise<ActionResponse> {
         const res = await Dmart.axiosDmartInstance.post<ActionResponse>(`managed/request`, action, {
             headers,
@@ -253,6 +356,13 @@ export class Dmart {
         return res?.data;
     }
 
+    /**
+     * Retrieves a specific entry from the Dmart system
+     * @param request - RetrieveEntryRequest containing entry identification and retrieval options
+     * @param scope - The scope for the retrieval (default: DmartScope.managed)
+     * @returns Promise resolving to ResponseEntry with entry data or null if not found
+     * @throws Error if entry retrieval fails
+     */
     public static async retrieveEntry(
         request: RetrieveEntryRequest,
         scope: string = DmartScope.managed
@@ -274,6 +384,13 @@ export class Dmart {
     }
 
 
+    /**
+     * Uploads a resource with an attached payload file
+     * @param request - UploadWithPayloadRequest containing resource data and payload file
+     * @param scope - The scope for the upload operation (default: DmartScope.managed)
+     * @returns Promise resolving to ApiResponse with upload result
+     * @throws Error if upload fails
+     */
     public static async uploadWithPayload(
         request: UploadWithPayloadRequest,
         scope: string = DmartScope.managed
@@ -317,6 +434,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Fetches data assets from the Dmart system with optional SQL query filtering
+     * @param request - FetchDataAssetRequest containing asset identification and query parameters
+     * @returns Promise resolving to data asset response
+     * @throws Error if data asset fetch fails
+     */
     public static async fetchDataAsset(
         request: FetchDataAssetRequest,
     ) {
@@ -340,6 +463,10 @@ export class Dmart {
         }
     }
 
+    /**
+     * Retrieves a list of all available spaces in the system
+     * @returns Promise resolving to ApiResponse containing spaces data or null
+     */
     public static async getSpaces(): Promise<ApiResponse | null> {
         return await this.query({
             type: QueryType.spaces,
@@ -350,6 +477,11 @@ export class Dmart {
         });
     }
 
+    /**
+     * Gets child resources within a specified space and subpath
+     * @param request - GetChildrenRequest containing search parameters and filters
+     * @returns Promise resolving to ApiResponse with child resources or null
+     */
     public static async getChildren(
         request: GetChildrenRequest
     ): Promise<ApiResponse | null> {
@@ -374,6 +506,12 @@ export class Dmart {
         });
     }
 
+    /**
+     * Generates a URL for accessing attachment resources
+     * @param request - GetAttachmentURLRequest containing attachment identification parameters
+     * @param scope - The scope for the attachment URL (default: DmartScope.managed)
+     * @returns String URL for accessing the attachment
+     */
     public static getAttachmentUrl(
         request: GetAttachmentURLRequest,
         scope: string = DmartScope.managed
@@ -384,6 +522,12 @@ export class Dmart {
         )}/${request.parent_shortname}/${request.shortname}${request.ext === null ? "" : `.${request.ext}`}`;
     }
 
+    /**
+     * Retrieves health information and statistics for a specific space
+     * @param space_name - The name of the space to check health for
+     * @returns Promise resolving to ApiQueryResponse with health data and folders report
+     * @throws Error if health check fails
+     */
     public static async getSpaceHealth(space_name: string) {
         try {
             const {data} = await Dmart.axiosDmartInstance.get<
@@ -395,6 +539,13 @@ export class Dmart {
         }
     }
 
+    /**
+     * Retrieves payload data for a specific resource
+     * @param request - GetPayloadRequest containing payload identification parameters
+     * @param scope - The scope for the payload retrieval (default: DmartScope.managed)
+     * @returns Promise resolving to payload data
+     * @throws Error if payload retrieval fails
+     */
     public static async getPayload(
         request: GetPayloadRequest,
         scope: string = DmartScope.managed
@@ -416,6 +567,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Updates the progress of a ticket with resolution and comments
+     * @param request - ProgressTicketRequest containing ticket identification and update data
+     * @returns Promise resolving to ApiQueryResponse with progress update result
+     * @throws Error if ticket progress update fails
+     */
     public static async progressTicket(
         request: ProgressTicketRequest
     ) {
@@ -440,6 +597,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Submits data to a public endpoint with optional workflow processing
+     * @param request - SubmitRequest containing submission data and routing information
+     * @returns Promise resolving to submission response data
+     * @throws Error if submission fails
+     */
     public static async submit(
         request: SubmitRequest
     ) {
@@ -463,6 +626,11 @@ export class Dmart {
         }
     }
 
+    /**
+     * Retrieves the system manifest containing configuration and metadata
+     * @returns Promise resolving to manifest data
+     * @throws Error if manifest retrieval fails
+     */
     public static async getManifest() {
         try {
             const {data} = await Dmart.axiosDmartInstance.get<any>(`info/manifest`, {
@@ -474,6 +642,11 @@ export class Dmart {
         }
     }
 
+    /**
+     * Retrieves the system settings and configuration
+     * @returns Promise resolving to settings data
+     * @throws Error if settings retrieval fails
+     */
     public static async getSettings() {
         try {
             const {data} = await Dmart.axiosDmartInstance.get<any>(`info/settings`, {
@@ -485,6 +658,13 @@ export class Dmart {
         }
     }
 
+    /**
+     * Sends an OTP (One-Time Password) request to a user
+     * @param request - SendOTPRequest containing recipient information
+     * @param acceptLanguage - Optional language preference for the OTP message (default: null)
+     * @returns Promise resolving to ApiResponse with OTP request result
+     * @throws Error if OTP request fails
+     */
     public static async otpRequest(
         request: SendOTPRequest,
         acceptLanguage: string | null = null
@@ -506,6 +686,13 @@ export class Dmart {
         }
     }
 
+    /**
+     * Sends an OTP (One-Time Password) request for login purposes
+     * @param request - SendOTPRequest containing recipient information for login OTP
+     * @param acceptLanguage - Optional language preference for the OTP message (default: null)
+     * @returns Promise resolving to ApiResponse with OTP login request result
+     * @throws Error if OTP login request fails
+     */
     public static async otpRequestLogin(
         request: SendOTPRequest,
         acceptLanguage: string | null = null
@@ -527,6 +714,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Initiates a password reset request for a user
+     * @param request - PasswordResetRequest containing user identification for password reset
+     * @returns Promise resolving to ApiResponse with password reset request result
+     * @throws Error if password reset request fails
+     */
     public static async passwordResetRequest(request: PasswordResetRequest) {
         try {
             const {data} = await Dmart.axiosDmartInstance.post<ApiResponse>(
@@ -540,6 +733,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Confirms an OTP (One-Time Password) code provided by the user
+     * @param request - ConfirmOTPRequest containing the OTP code and verification details
+     * @returns Promise resolving to ApiResponse with OTP confirmation result
+     * @throws Error if OTP confirmation fails
+     */
     public static async confirmOtp(request: ConfirmOTPRequest) {
         try {
             const {data} = await Dmart.axiosDmartInstance.post<ApiResponse>(
@@ -553,6 +752,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Resets a user's account or session state
+     * @param shortname - The shortname (username) of the user to reset
+     * @returns Promise resolving to ApiResponse with user reset result
+     * @throws Error if user reset fails
+     */
     public static async userReset(shortname: string) {
         try {
             const {data} = await Dmart.axiosDmartInstance.post<ApiResponse>(
@@ -566,6 +771,12 @@ export class Dmart {
         }
     }
 
+    /**
+     * Validates a password against system password policies and requirements
+     * @param password - The password string to validate
+     * @returns Promise resolving to ApiResponse with validation result
+     * @throws Error if password validation fails
+     */
     public static async validatePassword(password: string) {
         try {
             const {data} = await Dmart.axiosDmartInstance.post<ApiResponse>(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edraj/tsdmart",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "A TypeScript implementation of the Dmart that depends on axios.",
   "author": "Kefah T. Issa",
   "email": "kefah.issa@gmail.com",