@c-rex/services 0.1.1 → 0.1.3

package/dist/index.d.mts

@@ -1,16 +1,40 @@
 import { CrexApi } from '@c-rex/core';
 import { Method } from 'axios';
-import { informationUnitsRenditions, DirectoryNodes, informationUnits, informationUnitsItems, LanguageAndCountries } from '@c-rex/interfaces';
+import { informationUnitsRenditions, DirectoryNodes, DirectoryNodesResponse, informationUnitsResponse, informationUnitsItems, LanguageAndCountries } from '@c-rex/interfaces';
 
 type QueryParams = {
     key: string;
     value: string;
 };
+type FileRenditionType = {
+    format: string;
+    link: string;
+};
 
+/**
+ * Base service class that provides common functionality for API interactions.
+ * All specific service classes extend this base class.
+ */
 declare class BaseService {
     protected api: CrexApi;
     private endpoint;
+    /**
+     * Creates a new instance of BaseService.
+     *
+     * @param endpoint - The API endpoint URL for this service
+     */
     constructor(endpoint: string);
+    /**
+     * Makes an API request to the specified endpoint.
+     *
+     * @param options - Request configuration options
+     * @param options.path - Optional path to append to the endpoint
+     * @param options.params - Optional query parameters to include in the request
+     * @param options.method - HTTP method to use (defaults to 'get')
+     * @param options.transformer - Optional function to transform the response data
+     * @returns The response data, optionally transformed
+     * @throws Error if the API request fails
+     */
     protected request<T>({ path, method, params, headers, transformer, }: {
         path?: string;
         method?: Method;
@@ -20,41 +44,147 @@ declare class BaseService {
     }): Promise<T>;
 }
 
+/**
+ * Service for interacting with renditions in the API.
+ * Provides methods to retrieve and process different types of renditions.
+ */
 declare class RenditionsService extends BaseService {
     constructor();
-    getHTMLRendition(renditions: informationUnitsRenditions[]): Promise<string>;
-    getDocumentRendition(renditions: informationUnitsRenditions[], type: string): Promise<string>;
+    /**
+     * Retrieves the HTML rendition from a list of renditions.
+     * Filters for renditions with format 'application/xhtml+xml' and rel 'view'.
+     *
+     * @param renditions - Array of rendition objects to process
+     * @returns A promise that resolves to the HTML content as a string, or empty string if no suitable rendition is found
+     * @throws Error if the API request fails
+     */
+    getHTMLRendition({ renditions }: {
+        renditions: informationUnitsRenditions[];
+    }): Promise<string>;
+    /**
+     * Processes a list of renditions and categorizes them into files to download and files to open.
+     * Excludes renditions with formats 'application/xhtml+xml', 'application/json', and 'application/llm+xml'.
+     *
+     * @param renditions - Array of rendition objects to process
+     * @returns An object containing arrays of file renditions categorized as 'filesToDownload' and 'filesToOpen'
+     */
+    getFileRenditions: ({ renditions }: {
+        renditions: informationUnitsRenditions[];
+    }) => {
+        filesToDownload: FileRenditionType[];
+        filesToOpen: FileRenditionType[];
+    };
 }
 
+/**
+ * Service for interacting with directory nodes in the API.
+ * Provides methods to retrieve directory node information.
+ */
 declare class DirectoryNodesService extends BaseService {
     constructor();
+    /**
+     * Retrieves a specific directory node by its ID.
+     *
+     * @param id - The unique identifier of the directory node
+     * @returns A promise that resolves to the directory node data
+     * @throws Error if the API request fails
+     */
     getItem(id: string): Promise<DirectoryNodes>;
+    /**
+     * Retrieves a list of directory nodes based on specified filters.
+     *
+     * @param options - Options for filtering the directory nodes list
+     * @param options.filters - Optional array of filter strings to apply
+     * @returns A promise that resolves to the directory nodes response
+     * @throws Error if the API request fails
+     */
+    getList({ filters, }: {
+        filters?: string[];
+    }): Promise<DirectoryNodesResponse>;
 }
 
+/**
+ * Service for interacting with document types in the API.
+ * Provides methods to retrieve document type information.
+ */
 declare class DocumentTypesService extends BaseService {
     constructor();
+    /**
+     * Retrieves document type labels for the specified fields.
+     * The labels are restricted to English language (EN-us).
+     *
+     * @param fields - Array of field names to retrieve labels for
+     * @returns A promise that resolves to an array of label strings
+     * @throws Error if the API request fails
+     */
     getLabels(fields: string[]): Promise<string[]>;
 }
 
+/**
+ * Service for interacting with information units in the API.
+ * Provides methods to retrieve and search information units.
+ */
 declare class InformationUnitsService extends BaseService {
     constructor();
+    /**
+     * Retrieves a list of information units based on specified criteria.
+     *
+     * @param options - Options for filtering and paginating the information units list
+     * @param options.queries - Optional search query string
+     * @param options.page - Optional page number for pagination (defaults to 1)
+     * @param options.fields - Optional array of fields to include in the response
+     * @param options.filters - Optional array of filter strings to apply
+     * @param options.languages - Optional array of language codes to filter by
+     * @returns A promise that resolves to the information units response
+     * @throws Error if the API request fails
+     */
     getList({ queries, page, fields, filters, languages }: {
         queries?: string;
         page?: number;
         filters?: string[];
         fields?: string[];
         languages?: string[];
-    }): Promise<informationUnits>;
+    }): Promise<informationUnitsResponse>;
+    /**
+     * Retrieves a specific information unit by its ID.
+     * Includes renditions, directory nodes, version information, titles, languages, and labels.
+     *
+     * @param options - Options for retrieving the information unit
+     * @param options.id - The unique identifier of the information unit
+     * @returns A promise that resolves to the information unit data
+     * @throws Error if the API request fails
+     */
     getItem({ id }: {
         id: string;
     }): Promise<informationUnitsItems>;
-    getSuggestions({ query }: {
+    /**
+     * Retrieves autocomplete suggestions based on a query prefix.
+     *
+     * @param options - Options for retrieving suggestions
+     * @param options.query - The query prefix to get suggestions for
+     * @param options.language - The language of the suggestions
+     * @returns A promise that resolves to an array of suggestion strings
+     * @throws Error if the API request fails
+     */
+    getSuggestions({ query, language }: {
         query: string;
+        language: string;
     }): Promise<string[]>;
 }
 
+/**
+ * Service for interacting with language-related functionality in the API.
+ * Provides methods to retrieve language and country information.
+ */
 declare class LanguageService extends BaseService {
-    constructor(endpoint: string);
+    constructor();
+    /**
+     * Retrieves a list of available languages and their associated countries.
+     * Transforms the API response to include language code, country code, and original value.
+     *
+     * @returns A promise that resolves to an array of language and country objects
+     * @throws Error if the API request fails
+     */
     getLanguagesAndCountries(): Promise<LanguageAndCountries[]>;
 }
 

package/dist/index.d.ts

@@ -1,16 +1,40 @@
 import { CrexApi } from '@c-rex/core';
 import { Method } from 'axios';
-import { informationUnitsRenditions, DirectoryNodes, informationUnits, informationUnitsItems, LanguageAndCountries } from '@c-rex/interfaces';
+import { informationUnitsRenditions, DirectoryNodes, DirectoryNodesResponse, informationUnitsResponse, informationUnitsItems, LanguageAndCountries } from '@c-rex/interfaces';
 
 type QueryParams = {
     key: string;
     value: string;
 };
+type FileRenditionType = {
+    format: string;
+    link: string;
+};
 
+/**
+ * Base service class that provides common functionality for API interactions.
+ * All specific service classes extend this base class.
+ */
 declare class BaseService {
     protected api: CrexApi;
     private endpoint;
+    /**
+     * Creates a new instance of BaseService.
+     *
+     * @param endpoint - The API endpoint URL for this service
+     */
     constructor(endpoint: string);
+    /**
+     * Makes an API request to the specified endpoint.
+     *
+     * @param options - Request configuration options
+     * @param options.path - Optional path to append to the endpoint
+     * @param options.params - Optional query parameters to include in the request
+     * @param options.method - HTTP method to use (defaults to 'get')
+     * @param options.transformer - Optional function to transform the response data
+     * @returns The response data, optionally transformed
+     * @throws Error if the API request fails
+     */
     protected request<T>({ path, method, params, headers, transformer, }: {
         path?: string;
         method?: Method;
@@ -20,41 +44,147 @@ declare class BaseService {
     }): Promise<T>;
 }
 
+/**
+ * Service for interacting with renditions in the API.
+ * Provides methods to retrieve and process different types of renditions.
+ */
 declare class RenditionsService extends BaseService {
     constructor();
-    getHTMLRendition(renditions: informationUnitsRenditions[]): Promise<string>;
-    getDocumentRendition(renditions: informationUnitsRenditions[], type: string): Promise<string>;
+    /**
+     * Retrieves the HTML rendition from a list of renditions.
+     * Filters for renditions with format 'application/xhtml+xml' and rel 'view'.
+     *
+     * @param renditions - Array of rendition objects to process
+     * @returns A promise that resolves to the HTML content as a string, or empty string if no suitable rendition is found
+     * @throws Error if the API request fails
+     */
+    getHTMLRendition({ renditions }: {
+        renditions: informationUnitsRenditions[];
+    }): Promise<string>;
+    /**
+     * Processes a list of renditions and categorizes them into files to download and files to open.
+     * Excludes renditions with formats 'application/xhtml+xml', 'application/json', and 'application/llm+xml'.
+     *
+     * @param renditions - Array of rendition objects to process
+     * @returns An object containing arrays of file renditions categorized as 'filesToDownload' and 'filesToOpen'
+     */
+    getFileRenditions: ({ renditions }: {
+        renditions: informationUnitsRenditions[];
+    }) => {
+        filesToDownload: FileRenditionType[];
+        filesToOpen: FileRenditionType[];
+    };
 }
 
+/**
+ * Service for interacting with directory nodes in the API.
+ * Provides methods to retrieve directory node information.
+ */
 declare class DirectoryNodesService extends BaseService {
     constructor();
+    /**
+     * Retrieves a specific directory node by its ID.
+     *
+     * @param id - The unique identifier of the directory node
+     * @returns A promise that resolves to the directory node data
+     * @throws Error if the API request fails
+     */
     getItem(id: string): Promise<DirectoryNodes>;
+    /**
+     * Retrieves a list of directory nodes based on specified filters.
+     *
+     * @param options - Options for filtering the directory nodes list
+     * @param options.filters - Optional array of filter strings to apply
+     * @returns A promise that resolves to the directory nodes response
+     * @throws Error if the API request fails
+     */
+    getList({ filters, }: {
+        filters?: string[];
+    }): Promise<DirectoryNodesResponse>;
 }
 
+/**
+ * Service for interacting with document types in the API.
+ * Provides methods to retrieve document type information.
+ */
 declare class DocumentTypesService extends BaseService {
     constructor();
+    /**
+     * Retrieves document type labels for the specified fields.
+     * The labels are restricted to English language (EN-us).
+     *
+     * @param fields - Array of field names to retrieve labels for
+     * @returns A promise that resolves to an array of label strings
+     * @throws Error if the API request fails
+     */
     getLabels(fields: string[]): Promise<string[]>;
 }
 
+/**
+ * Service for interacting with information units in the API.
+ * Provides methods to retrieve and search information units.
+ */
 declare class InformationUnitsService extends BaseService {
     constructor();
+    /**
+     * Retrieves a list of information units based on specified criteria.
+     *
+     * @param options - Options for filtering and paginating the information units list
+     * @param options.queries - Optional search query string
+     * @param options.page - Optional page number for pagination (defaults to 1)
+     * @param options.fields - Optional array of fields to include in the response
+     * @param options.filters - Optional array of filter strings to apply
+     * @param options.languages - Optional array of language codes to filter by
+     * @returns A promise that resolves to the information units response
+     * @throws Error if the API request fails
+     */
     getList({ queries, page, fields, filters, languages }: {
         queries?: string;
         page?: number;
         filters?: string[];
         fields?: string[];
         languages?: string[];
-    }): Promise<informationUnits>;
+    }): Promise<informationUnitsResponse>;
+    /**
+     * Retrieves a specific information unit by its ID.
+     * Includes renditions, directory nodes, version information, titles, languages, and labels.
+     *
+     * @param options - Options for retrieving the information unit
+     * @param options.id - The unique identifier of the information unit
+     * @returns A promise that resolves to the information unit data
+     * @throws Error if the API request fails
+     */
     getItem({ id }: {
         id: string;
     }): Promise<informationUnitsItems>;
-    getSuggestions({ query }: {
+    /**
+     * Retrieves autocomplete suggestions based on a query prefix.
+     *
+     * @param options - Options for retrieving suggestions
+     * @param options.query - The query prefix to get suggestions for
+     * @param options.language - The language of the suggestions
+     * @returns A promise that resolves to an array of suggestion strings
+     * @throws Error if the API request fails
+     */
+    getSuggestions({ query, language }: {
         query: string;
+        language: string;
     }): Promise<string[]>;
 }
 
+/**
+ * Service for interacting with language-related functionality in the API.
+ * Provides methods to retrieve language and country information.
+ */
 declare class LanguageService extends BaseService {
-    constructor(endpoint: string);
+    constructor();
+    /**
+     * Retrieves a list of available languages and their associated countries.
+     * Transforms the API response to include language code, country code, and original value.
+     *
+     * @returns A promise that resolves to an array of language and country objects
+     * @throws Error if the API request fails
+     */
     getLanguagesAndCountries(): Promise<LanguageAndCountries[]>;
 }