mftsccs-node 0.2.13 → 0.2.15

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,5 +48,78 @@ export declare class TokenStorage {
      * Consider clearing this value on logout or session expiration.
      */
     static BearerAccessToken: string;
-    static JwtSecret: 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;
+    /**
+     * Token expiration timestamp (Unix timestamp in milliseconds)
+     * @static
+     * @type {number}
+     * @default 0
+     */
+    static TOKEN_EXPIRY: number;
+    /**
+     * Buffer time before token expiry to trigger refresh (in milliseconds)
+     * Default: 5 minutes (300000 ms)
+     * @static
+     * @type {number}
+     */
+    static EXPIRY_BUFFER_MS: number;
+    /**
+     * 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>;
+    /**
+     * Sets the access token and calculates expiry time.
+     * @param token - The access token
+     * @param expiresIn - Token lifetime in seconds (optional)
+     */
+    static setToken(token: string, expiresIn?: number): void;
+    /**
+     * Checks if the token is expired or near expiry.
+     * @returns {boolean} True if token is expired or within the buffer window
+     */
+    static isTokenExpiredOrNearExpiry(): boolean;
+    /**
+     * Gets the remaining time until token expiry in seconds.
+     * @returns {number} Seconds until expiry, or -1 if expired/no expiry set
+     */
+    static getTimeUntilExpiry(): number;
+    /**
+     * 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/Security/GetRequestHeader.d.ts

@@ -1,10 +1,58 @@
-export declare function GetRequestHeader(contentType?: string, Accept?: string): {
-    'Content-Type': string;
-    Authorization: string;
-    Accept: string;
-};
-export declare function GetRequestHeaderWithAuthorization(contentType?: string, token?: string, Accept?: string): {
-    'Content-Type': string;
-    Authorization: string;
-    Accept: string;
-};
+/**
+ * Gets request headers with automatic token refresh if expired or near expiry.
+ * This is the async version that checks token expiry and refreshes if needed.
+ *
+ * @async
+ * @param {string} [contentType='application/json'] - Content-Type header value
+ * @param {string} [Accept='application/json'] - Accept header value
+ * @returns {Promise<Record<string, string>>} Headers object with refreshed token if needed
+ *
+ * @example
+ * ```typescript
+ * // Automatically refreshes token if expired/near expiry
+ * const headers = await GetRequestHeaderWithRefresh();
+ * const response = await fetch(url, { headers });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom content type
+ * const headers = await GetRequestHeaderWithRefresh('application/x-www-form-urlencoded');
+ * ```
+ */
+export declare function GetRequestHeader(contentType?: string, Accept?: string): Promise<Record<string, string>>;
+/**
+ * Gets request headers with automatic token refresh and custom token override.
+ * This is the async version that checks token expiry and refreshes if needed.
+ *
+ * @async
+ * @param {string} [contentType='application/json'] - Content-Type header value
+ * @param {string} [token=''] - Optional token override. If empty, uses TokenStorage token
+ * @param {string} [Accept='application/json'] - Accept header value
+ * @returns {Promise<Record<string, string>>} Headers object with refreshed token if needed
+ *
+ * @example
+ * ```typescript
+ * // Use stored token with automatic refresh
+ * const headers = await GetRequestHeaderWithAuthorizationAndRefresh();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use custom token (no refresh)
+ * const headers = await GetRequestHeaderWithAuthorizationAndRefresh(
+ *     'application/json',
+ *     'custom-token-here'
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check token expiry status
+ * const timeRemaining = TokenStorage.getTimeUntilExpiry();
+ * console.log(`Token expires in ${timeRemaining} seconds`);
+ *
+ * const headers = await GetRequestHeaderWithAuthorizationAndRefresh();
+ * ```
+ */
+export declare function GetRequestHeaderWithAuthorization(contentType?: string, token?: string, Accept?: string): Promise<Record<string, string>>;

package/dist/types/Services/auth/AuthService.d.ts

@@ -1 +0,0 @@
-export declare const getServerJwtToken: () => string;

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>;