mftsccs-node 0.0.59 → 0.0.62

package/dist/types/DataStructures/BaseUrl.d.ts

@@ -259,4 +259,14 @@ export declare class BaseUrl {
      * @returns {string} The bulk type concept retrieval API endpoint
      */
     static GetConceptConnectionByType(): string;
+    /**
+     * Returns the URL for OAuth token requests.
+     * @returns {string} The OAuth token API endpoint
+     */
+    static OAuthTokenUrl(): string;
+    /**
+     * Returns the URL for OAuth token refresh requests.
+     * @returns {string} The OAuth token refresh API endpoint
+     */
+    static OAuthRefreshUrl(): string;
 }

package/dist/types/DataStructures/CCSConfig.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Configuration class for CCS initialization.
+ * This module provides a clean way to manage optional CCS configuration parameters.
+ * @module DataStructures/CCSConfig
+ */
+/**
+ * Configuration class for CCS initialization.
+ *
+ * This class holds all optional configuration parameters for the CCS library,
+ * keeping the init() function clean with only essential parameters.
+ *
+ * @class CCSConfig
+ *
+ * @example
+ * ```typescript
+ * const config = new CCSConfig({
+ *     aiUrl: "https://ai.example.com",
+ *     accessToken: "jwt-token",
+ *     enableAi: true,
+ *     flags: { logApplication: true },
+ *     storagePath: "./data/ccs/"
+ * });
+ *
+ * await init(
+ *     "https://api.example.com",
+ *     "http://localhost:5001",
+ *     "MyApp",
+ *     config
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Minimal configuration with OAuth
+ * const config = new CCSConfig({
+ *     clientId: "101084838",
+ *     clientSecret: "your-secret"
+ * });
+ *
+ * await init("https://api.example.com", "", "MyApp", config);
+ * ```
+ */
+export declare class CCSConfig {
+    /** URL for the AI service. Defaults to "https://ai.freeschema.com" */
+    aiUrl: string;
+    /** JWT bearer token for authentication. Can be set later via updateAccessToken() */
+    accessToken: string;
+    /** Whether to enable AI features. Defaults to true */
+    enableAi: boolean;
+    /**
+     * Dictionary of feature flags for controlling CCS behavior.
+     * Available flags:
+     * - logApplication: Enable application-level logging
+     * - logPackage: Enable package-level logging
+     * - accessTracker: Enable access tracking
+     * - isTest: Enable test mode
+     */
+    flags?: Record<string, boolean>;
+    /**
+     * Dictionary of additional parameters.
+     * Example: { logserver: "https://logs.example.com" }
+     */
+    parameters?: Record<string, string>;
+    /** Path for storing local data (ID counters, cached data, etc.) */
+    storagePath?: string;
+    /** OAuth client ID for authentication */
+    clientId?: string;
+    /** OAuth client secret for authentication */
+    clientSecret?: string;
+    /** Application name for OAuth and logging purposes */
+    applicationName?: string;
+    /**
+     * Creates a new CCSConfig instance.
+     *
+     * @param options - Partial configuration options to override defaults
+     *
+     * @example
+     * ```typescript
+     * // Use default values
+     * const config = new CCSConfig();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Override specific values
+     * const config = new CCSConfig({
+     *     aiUrl: "https://custom-ai.example.com",
+     *     enableAi: false,
+     *     clientId: "123456",
+     *     clientSecret: "secret",
+     *     flags: {
+     *         logApplication: true,
+     *         accessTracker: true
+     *     }
+     * });
+     * ```
+     */
+    constructor(options?: Partial<CCSConfig>);
+    /**
+     * Returns true if OAuth credentials are configured.
+     * @returns {boolean} Whether both clientId and clientSecret are set
+     */
+    hasOAuthCredentials(): boolean;
+    /**
+     * Returns true if an access token is configured.
+     * @returns {boolean} Whether accessToken is set
+     */
+    hasAccessToken(): boolean;
+    /**
+     * Get a specific flag value with a default fallback.
+     *
+     * @param flagName - The name of the flag to retrieve
+     * @param defaultValue - Default value if flag is not set
+     * @returns {boolean} The flag value or default
+     *
+     * @example
+     * ```typescript
+     * const config = new CCSConfig({
+     *     flags: { logApplication: true }
+     * });
+     * config.getFlag('logApplication', false); // returns true
+     * config.getFlag('unknownFlag', false);     // returns false
+     * ```
+     */
+    getFlag(flagName: string, defaultValue?: boolean): boolean;
+    /**
+     * Get a specific parameter value with a default fallback.
+     *
+     * @param paramName - The name of the parameter to retrieve
+     * @param defaultValue - Default value if parameter is not set
+     * @returns {string} The parameter value or default
+     *
+     * @example
+     * ```typescript
+     * const config = new CCSConfig({
+     *     parameters: { logserver: "https://logs.example.com" }
+     * });
+     * config.getParameter('logserver', ''); // returns "https://logs.example.com"
+     * config.getParameter('unknown', '');   // returns ""
+     * ```
+     */
+    getParameter(paramName: string, defaultValue?: string): string;
+    /**
+     * Set a flag value.
+     *
+     * @param flagName - The name of the flag to set
+     * @param value - The boolean value to set
+     *
+     * @example
+     * ```typescript
+     * const config = new CCSConfig();
+     * config.setFlag('logApplication', true);
+     * ```
+     */
+    setFlag(flagName: string, value: boolean): void;
+    /**
+     * Set a parameter value.
+     *
+     * @param paramName - The name of the parameter to set
+     * @param value - The string value to set
+     *
+     * @example
+     * ```typescript
+     * const config = new CCSConfig();
+     * config.setParameter('logserver', 'https://logs.example.com');
+     * ```
+     */
+    setParameter(paramName: string, value: string): void;
+}

package/dist/types/DataStructures/Security/TokenStorage.d.ts

@@ -48,4 +48,48 @@ export declare class TokenStorage {
      * Consider clearing this value on logout or session expiration.
      */
     static BearerAccessToken: string;
+    /**
+     * OAuth client ID for token refresh
+     * @static
+     * @type {string}
+     * @default ""
+     */
+    static CLIENT_ID: string;
+    /**
+     * OAuth client secret for token refresh
+     * @static
+     * @type {string}
+     * @default ""
+     */
+    static CLIENT_SECRET: string;
+    /**
+     * Application name for OAuth
+     * @static
+     * @type {string}
+     * @default ""
+     */
+    static APPLICATION_NAME: string;
+    /**
+     * Gets authorization header object for HTTP requests.
+     * @returns {Record<string, string>} Headers object with Authorization header if token exists
+     *
+     * @example
+     * ```typescript
+     * const headers = TokenStorage.getAuthHeader();
+     * // Returns: { 'Authorization': 'Bearer your-token' } or {}
+     * ```
+     */
+    static getAuthHeader(): Record<string, string>;
+    /**
+     * Checks if OAuth credentials are configured for automatic token refresh.
+     * @returns {boolean} True if client ID, secret, and app name are all set
+     */
+    static hasOAuthCredentials(): boolean;
+    /**
+     * Sets OAuth credentials for automatic token refresh.
+     * @param clientId - OAuth client ID
+     * @param clientSecret - OAuth client secret
+     * @param applicationName - Application name
+     */
+    static setOAuthCredentials(clientId: string, clientSecret: string, applicationName: string): void;
 }

package/dist/types/Services/Common/ErrorPosting.d.ts

@@ -2,6 +2,7 @@
  * @module ErrorPosting
  * @description Provides error handling functions for HTTP and internal errors with structured error responses
  */
+import { HttpResponse } from "../Http/HttpClient.service";
 /**
  * Handles HTTP errors by creating and throwing structured error responses.
  * Specifically handles 401 Unauthorized errors.
@@ -23,6 +24,7 @@
  * - Useful for API call error handling
  */
 export declare function HandleHttpError(response: Response): void;
+export declare function HandleHttpErrorHttp(response: HttpResponse): void;
 /**
  * Handles internal application errors by creating and throwing structured error responses.
  * Wraps any error object into a FreeSchemaResponse.

package/dist/types/Services/Http/HttpClient.service.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview HTTP Client - Handles API requests with automatic token refresh on 401 errors.
+ * This module provides a robust HTTP client that automatically refreshes OAuth tokens
+ * when receiving 401 Unauthorized responses, ensuring seamless API access.
+ * @module Services/Http/HttpClient
+ */
+/**
+ * Custom error thrown when token refresh fails.
+ */
+export declare class TokenRefreshError extends Error {
+    constructor(message: string);
+}
+/**
+ * Container for HTTP response data.
+ * Provides convenient methods to parse response body as JSON or text.
+ */
+export declare class HttpResponse {
+    status: number;
+    body: string;
+    headers: Record<string, string>;
+    /**
+     * Creates a new HttpResponse instance.
+     * @param status - HTTP status code
+     * @param body - Response body as string
+     * @param headers - Response headers
+     */
+    constructor(status: number, body: string, headers: Record<string, string>);
+    /**
+     * Parse response body as JSON.
+     * @returns {Promise<any>} Parsed JSON object
+     *
+     * @example
+     * ```typescript
+     * const response = await requestWithRetry('GET', url);
+     * const data = await response.json();
+     * console.log(data.id);
+     * ```
+     */
+    json(): Promise<any>;
+    /**
+     * Get response body as text.
+     * @returns {Promise<string>} Response body as string
+     *
+     * @example
+     * ```typescript
+     * const response = await requestWithRetry('GET', url);
+     * const text = await response.text();
+     * console.log(text);
+     * ```
+     */
+    text(): Promise<string>;
+    /**
+     * Checks if the response status indicates success (200-299).
+     * @returns {boolean} True if status is in the 2xx range
+     */
+    get ok(): boolean;
+}
+/**
+ * Make an HTTP request with automatic retry on 401 Unauthorized.
+ *
+ * If a 401 error occurs and OAuth credentials are available, this function
+ * will automatically refresh the token and retry the request once.
+ *
+ * @async
+ * @param {string} method - HTTP method (GET, POST, PUT, DELETE, etc.)
+ * @param {string} url - The URL to request
+ * @param {Record<string, string>} [headers] - Optional headers dict
+ * @param {any} [body] - Optional request body (JSON will be stringified)
+ * @param {number} [maxRetries=1] - Maximum number of retries on 401
+ * @returns {Promise<HttpResponse>} HttpResponse object with status, body, and headers
+ * @throws {TokenRefreshError} If token refresh fails
+ * @throws {Error} For other network errors
+ *
+ * @example
+ * ```typescript
+ * const headers = { "Content-Type": "application/json" };
+ * const response = await requestWithRetry(
+ *     "POST",
+ *     url,
+ *     headers,
+ *     { id: 123 }
+ * );
+ * if (response.ok) {
+ *     const data = await response.json();
+ *     console.log(data);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Automatic token refresh on 401
+ * try {
+ *     const response = await requestWithRetry("GET", url);
+ *     // If receives 401, will automatically refresh token and retry
+ * } catch (error) {
+ *     if (error instanceof TokenRefreshError) {
+ *         console.error('Authentication failed:', error.message);
+ *     }
+ * }
+ * ```
+ */
+export declare function requestWithRetry(method: string, url: string, headers?: Record<string, string>, body?: any, maxRetries?: number): Promise<HttpResponse>;
+/**
+ * Convenience method for POST requests with automatic retry on 401.
+ *
+ * @async
+ * @param {string} url - The URL to request
+ * @param {Record<string, string>} [headers] - Optional headers dict
+ * @param {any} [body] - Optional request body (will be JSON stringified if object)
+ * @returns {Promise<HttpResponse>} HttpResponse object
+ *
+ * @example
+ * ```typescript
+ * const response = await postWithRetry(
+ *     "https://api.example.com/concepts",
+ *     { "Content-Type": "application/json" },
+ *     { name: "Test", value: 123 }
+ * );
+ * if (response.ok) {
+ *     const data = await response.json();
+ *     console.log('Created:', data);
+ * }
+ * ```
+ */
+export declare function postWithRetry(url: string, headers?: Record<string, string>, body?: any): Promise<HttpResponse>;
+/**
+ * Convenience method for GET requests with automatic retry on 401.
+ *
+ * @async
+ * @param {string} url - The URL to request
+ * @param {Record<string, string>} [headers] - Optional headers dict
+ * @param {Record<string, any>} [params] - Optional query parameters
+ * @returns {Promise<HttpResponse>} HttpResponse object
+ *
+ * @example
+ * ```typescript
+ * const response = await getWithRetry(
+ *     "https://api.example.com/concepts",
+ *     undefined,
+ *     { id: 123, type: "test" }
+ * );
+ * if (response.ok) {
+ *     const data = await response.json();
+ *     console.log(data);
+ * }
+ * ```
+ */
+export declare function getWithRetry(url: string, headers?: Record<string, string>, params?: Record<string, any>): Promise<HttpResponse>;
+/**
+ * Convenience method for PUT requests with automatic retry on 401.
+ *
+ * @async
+ * @param {string} url - The URL to request
+ * @param {Record<string, string>} [headers] - Optional headers dict
+ * @param {any} [body] - Optional request body
+ * @returns {Promise<HttpResponse>} HttpResponse object
+ *
+ * @example
+ * ```typescript
+ * const response = await putWithRetry(
+ *     "https://api.example.com/concepts/123",
+ *     { "Content-Type": "application/json" },
+ *     { name: "Updated Name" }
+ * );
+ * ```
+ */
+export declare function putWithRetry(url: string, headers?: Record<string, string>, body?: any): Promise<HttpResponse>;
+/**
+ * Convenience method for DELETE requests with automatic retry on 401.
+ *
+ * @async
+ * @param {string} url - The URL to request
+ * @param {Record<string, string>} [headers] - Optional headers dict
+ * @returns {Promise<HttpResponse>} HttpResponse object
+ *
+ * @example
+ * ```typescript
+ * const response = await deleteWithRetry(
+ *     "https://api.example.com/concepts/123"
+ * );
+ * if (response.ok) {
+ *     console.log('Deleted successfully');
+ * }
+ * ```
+ */
+export declare function deleteWithRetry(url: string, headers?: Record<string, string>): Promise<HttpResponse>;
+/**
+ * Convenience method for PATCH requests with automatic retry on 401.
+ *
+ * @async
+ * @param {string} url - The URL to request
+ * @param {Record<string, string>} [headers] - Optional headers dict
+ * @param {any} [body] - Optional request body
+ * @returns {Promise<HttpResponse>} HttpResponse object
+ *
+ * @example
+ * ```typescript
+ * const response = await patchWithRetry(
+ *     "https://api.example.com/concepts/123",
+ *     { "Content-Type": "application/json" },
+ *     { status: "active" }
+ * );
+ * ```
+ */
+export declare function patchWithRetry(url: string, headers?: Record<string, string>, body?: any): Promise<HttpResponse>;

package/dist/types/Services/oauth/CallOauth.service.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview OAuth API - Handles OAuth token requests for authentication.
+ * This module provides functions for obtaining and refreshing OAuth access tokens
+ * from the authentication server.
+ * @module Services/oauth/CallOauth
+ */
+/**
+ * Response from OAuth token request.
+ * Contains either successful token data or error information.
+ *
+ * @interface OAuthResponse
+ */
+export interface OAuthResponse {
+    /** Whether the OAuth request was successful */
+    success: boolean;
+    /** The OAuth access token (empty if request failed) */
+    access_token?: string;
+    /** The token type (typically "Bearer") */
+    token_type?: string;
+    /** Number of seconds until the token expires */
+    expires_in?: number;
+    /** Error message if the request failed */
+    error?: string;
+}
+/**
+ * Request an OAuth access token from the server.
+ *
+ * This function authenticates with the OAuth endpoint using client credentials
+ * and returns an access token that can be used for API requests.
+ *
+ * @async
+ * @param {string} client_id - The OAuth client ID.
+ * @param {string} client_secret - The OAuth client secret.
+ * @param {string} application_name - The name of the application requesting the token.
+ * @param {boolean} [auto_set_token=true] - If true, automatically sets the token in TokenStorage
+ *                                          for subsequent API calls.
+ * @returns {Promise<OAuthResponse>} OAuthResponse with the access token if successful,
+ *                                    or error details if failed.
+ *
+ * @example
+ * ```typescript
+ * import { getOAuthToken } from './Services/oauth/CallOauth.service';
+ *
+ * const response = await getOAuthToken(
+ *     "101084838",
+ *     "your-client-secret",
+ *     "myapp"
+ * );
+ * if (response.success) {
+ *     console.log(`Token: ${response.access_token}`);
+ * } else {
+ *     console.log(`Error: ${response.error}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get token without auto-setting
+ * const response = await getOAuthToken(
+ *     "101084838",
+ *     "secret",
+ *     "myapp",
+ *     false
+ * );
+ * // Manually set token later
+ * if (response.success) {
+ *     TokenStorage.BearerAccessToken = response.access_token || "";
+ * }
+ * ```
+ */
+export declare function getOAuthToken(client_id: string, client_secret: string, application_name: string, auto_set_token?: boolean): Promise<OAuthResponse>;
+/**
+ * Refresh an OAuth access token using a refresh token.
+ *
+ * This function uses a refresh token from a previous authentication to obtain
+ * a new access token without requiring the user to re-authenticate.
+ *
+ * @async
+ * @param {string} client_id - The OAuth client ID.
+ * @param {string} client_secret - The OAuth client secret.
+ * @param {string} refresh_token - The refresh token from a previous authentication.
+ * @param {boolean} [auto_set_token=true] - If true, automatically sets the new token in TokenStorage.
+ * @returns {Promise<OAuthResponse>} OAuthResponse with the new access token if successful.
+ *
+ * @example
+ * ```typescript
+ * import { refreshOAuthToken } from './Services/oauth/CallOauth.service';
+ *
+ * const response = await refreshOAuthToken(
+ *     "101084838",
+ *     "your-client-secret",
+ *     "your-refresh-token"
+ * );
+ * if (response.success) {
+ *     console.log(`New Token: ${response.access_token}`);
+ * } else {
+ *     console.log(`Error: ${response.error}`);
+ * }
+ * ```
+ */
+export declare function refreshOAuthToken(client_id: string, client_secret: string, refresh_token: string, auto_set_token?: boolean): Promise<OAuthResponse>;

package/dist/types/app.d.ts

@@ -7,6 +7,8 @@
  * @see {@link https://documentation.freeschema.com} for detailed documentation
  */
 export { init, updateAccessToken };
+export { getOAuthToken, refreshOAuthToken, OAuthResponse } from './Services/oauth/CallOauth.service';
+export { requestWithRetry, postWithRetry, getWithRetry, putWithRetry, deleteWithRetry, patchWithRetry, HttpResponse, TokenRefreshError } from './Services/Http/HttpClient.service';
 export { SplitStrings } from './Services/SplitStrings';
 export { GetCompositionList, GetCompositionListWithId } from './Services/GetCompositionList';
 export { GetCompositionListLocal, GetCompositionListLocalWithId } from './Services/Local/GetCompositionListLocal';
@@ -89,7 +91,10 @@ export { UserBinaryTree } from './DataStructures/User/UserBinaryTree';
 export { FilterSearch } from './DataStructures/FilterSearch';
 export { SearchStructure } from './DataStructures/Search/SearchStructure';
 export { FreeSchemaResponse } from './DataStructures/Responses/ErrorResponse';
+export { CCSConfig } from './DataStructures/CCSConfig';
+import { CCSConfig } from './DataStructures/CCSConfig';
 export { BaseUrl } from './DataStructures/BaseUrl';
+export { TokenStorage } from './DataStructures/Security/TokenStorage';
 export { SchemaQueryListener } from './WrapperFunctions/SchemaQueryObservable';
 export { FreeschemaQuery } from './DataStructures/Search/FreeschemaQuery';
 export { GiveConnection, GetAllTheConnectionsByTypeAndOfTheConcept } from './Services/Delete/GetAllConnectionByType';
@@ -117,7 +122,7 @@ declare function updateAccessToken(accessToken?: string): void;
  * It performs the following operations asynchronously:
  *
  * 1. Sets up base URLs for the main API and AI services
- * 2. Stores the authentication token for API requests
+ * 2. Stores the authentication token for API requests (or obtains one via OAuth)
  * 3. Initializes the system (database setup)
  * 4. Creates binary trees from concept data for efficient querying (by ID, character, and type)
  * 5. Creates local binary trees for offline/local concept management
@@ -128,22 +133,54 @@ declare function updateAccessToken(accessToken?: string): void;
  * are updated as each operation completes to indicate which data structures are ready for use.
  *
  * @param url - The base URL for the main backend API endpoint (e.g., 'https://api.example.com')
- * @param aiurl - The base URL for the AI service endpoint (e.g., 'https://ai.example.com')
- * @param accessToken - The bearer access token for authenticating API requests
+ * @param nodeUrl - The base URL for the Node.js service endpoint (optional)
+ * @param applicationName - The name of the application (used for OAuth and logging)
+ * @param config - Optional CCSConfig object containing all optional configuration parameters
  *
  * @example
  * ```typescript
- * // Initialize the system with backend URLs and auth token
- * init(
- *   'https://api.freeschema.com',
- *   'https://ai.freeschema.com',
- *   'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
- * );
+ * // Simple initialization with just URL
+ * init('https://api.freeschema.com');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Initialize with access token
+ * const config = new CCSConfig({
+ *     accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+ * });
+ * init('https://api.freeschema.com', '', 'MyApp', config);
+ * ```
  *
- * // After initialization, check if data is loaded before querying
- * if (IdentifierFlags.isDataLoaded) {
- *   // Safe to query concepts
- * }
+ * @example
+ * ```typescript
+ * // Initialize with OAuth credentials
+ * const config = new CCSConfig({
+ *     clientId: '101084838',
+ *     clientSecret: 'your-client-secret',
+ *     aiUrl: 'https://ai.freeschema.com',
+ *     enableAi: true
+ * });
+ * init('https://api.freeschema.com', '', 'MyApp', config);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Full configuration
+ * const config = new CCSConfig({
+ *     aiUrl: 'https://ai.example.com',
+ *     accessToken: 'token',
+ *     enableAi: true,
+ *     flags: {
+ *         logApplication: true,
+ *         accessTracker: true
+ *     },
+ *     parameters: {
+ *         logserver: 'https://logs.example.com'
+ *     },
+ *     storagePath: './data/ccs/'
+ * });
+ * init('https://api.example.com', 'http://localhost:5001', 'MyApp', config);
  * ```
  *
  * @remarks
@@ -154,9 +191,10 @@ declare function updateAccessToken(accessToken?: string): void;
  * - `isConnectionLoaded`, `isConnectionTypeLoaded` - Remote connection data ready
  * - `isLocalConnectionLoaded` - Local connection data ready
  *
+ * @see CCSConfig for all available configuration options
  * @see IdentifierFlags for checking initialization status
  * @see InitializeSystem for database initialization details
  * @see CreateBinaryTreeFromData for concept tree creation
  * @see https://documentation.freeschema.com/#installation for setup guide
  */
-declare function init(url?: string, aiurl?: string, accessToken?: string): void;
+declare function init(url?: string, nodeUrl?: string, applicationName?: string, config?: CCSConfig): void;