mftsccs-node 0.2.7 → 0.2.9

package/dist/types/DataStructures/Session/SessionData.d.ts

@@ -1,13 +1,131 @@
+/**
+ * @fileoverview Defines the SessionData class for storing session information.
+ * @module DataStructures/Session/SessionData
+ */
+/**
+ * Represents session information for a user's connection.
+ * This class stores comprehensive details about a user's session, including
+ * network information, server configuration, and user identification data.
+ * It captures both client and server-side information for session tracking and security purposes.
+ *
+ * @class SessionData
+ *
+ * @example
+ * ```typescript
+ * const session = new SessionData();
+ * session.id = "abc123def456";
+ * session.userId = "12345";
+ * session.email = "user@example.com";
+ * session.remote_address = "192.168.1.100";
+ * session.http_user_agent = "Mozilla/5.0...";
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Populate session data from request
+ * const session = new SessionData();
+ * session.remote_address = request.connection.remoteAddress;
+ * session.server_port = process.env.PORT;
+ * session.server_name = request.hostname;
+ * ```
+ */
 export declare class SessionData {
+    /**
+     * The unique session identifier.
+     * Used to track and identify individual sessions across requests.
+     *
+     * @type {string}
+     * @default "0"
+     */
     id: string;
+    /**
+     * The remote IP address of the client.
+     * Identifies the network address from which the client is connecting.
+     *
+     * @type {string}
+     * @default ""
+     *
+     * @example "192.168.1.100" or "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
+     */
     remote_address: string;
+    /**
+     * The port number on which the server is listening.
+     * Indicates which server port is handling the connection.
+     *
+     * @type {string}
+     * @default ""
+     *
+     * @example "8080" or "443"
+     */
     server_port: string;
+    /**
+     * The server's IP address.
+     * Identifies the network address of the server handling the request.
+     *
+     * @type {string}
+     * @default ""
+     */
     server_address: string;
+    /**
+     * The server's hostname or domain name.
+     * The fully qualified domain name or hostname of the server.
+     *
+     * @type {string}
+     * @default ""
+     *
+     * @example "api.example.com" or "localhost"
+     */
     server_name: string;
+    /**
+     * Information about the server software.
+     * Identifies the server software and version handling the request.
+     *
+     * @type {string}
+     * @default ""
+     *
+     * @example "Apache/2.4.41" or "nginx/1.18.0"
+     */
     server_software: string;
+    /**
+     * The HTTP User-Agent header from the client.
+     * Contains information about the client's browser or application making the request.
+     *
+     * @type {string}
+     * @default ""
+     *
+     * @example "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..."
+     */
     http_user_agent: string;
+    /**
+     * The self-referential identifier or URL.
+     * May contain a reference to the current script or endpoint.
+     *
+     * @type {string}
+     * @default ""
+     */
     self: string;
+    /**
+     * The client's port number.
+     * Indicates which port on the client side is being used for the connection.
+     *
+     * @type {string}
+     * @default ""
+     */
     port: string;
+    /**
+     * The user's unique identifier.
+     * Links the session to a specific user account.
+     *
+     * @type {string}
+     * @default ""
+     */
     userId: string;
+    /**
+     * The user's email address.
+     * Stores the authenticated user's email for session tracking.
+     *
+     * @type {string}
+     * @default ""
+     */
     email: string;
 }

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

@@ -1,5 +1,37 @@
+/**
+ * @fileoverview SettingData module for managing persisted setting data in CCS-JS.
+ * This module defines the structure for storing user preferences and configuration.
+ * @module DataStructures/SettingData
+ */
+/**
+ * Represents persisted setting data for the application.
+ * Can be stored in local storage or IndexedDB for user preferences.
+ *
+ * @class SettingData
+ * @example
+ * ```typescript
+ * // Create settings with online sync enabled
+ * const settings = new SettingData(true);
+ *
+ * // Store settings
+ * localStorage.setItem('settings', JSON.stringify(settings));
+ * ```
+ */
 export declare class SettingData {
+    /** Unique identifier for the settings record */
     id: number;
+    /** Controls whether online synchronization is enabled */
     isOnlineSync: boolean;
+    /**
+     * Creates a new SettingData instance.
+     *
+     * @param {boolean} isOnlineSync - Whether to enable online synchronization
+     *
+     * @example
+     * ```typescript
+     * const settings = new SettingData(true);
+     * console.log(settings.isOnlineSync); // true
+     * ```
+     */
     constructor(isOnlineSync: boolean);
 }

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

@@ -1,4 +1,31 @@
+/**
+ * @fileoverview Settings module for managing global application settings in CCS-JS.
+ * This module provides centralized configuration flags for application behavior.
+ * @module DataStructures/Settings
+ */
+/**
+ * Global application settings for CCS-JS.
+ * Controls application-wide behavior such as update status and synchronization mode.
+ *
+ * @class Settings
+ * @example
+ * ```typescript
+ * // Enable online sync
+ * Settings.isOnlineSync = true;
+ *
+ * // Check if system is updated
+ * if (Settings.isUpdated) {
+ *   console.log("System is up to date");
+ * }
+ * ```
+ *
+ * @remarks
+ * All properties are static flags used across the application.
+ * These settings affect how data is synchronized and persisted.
+ */
 export declare class Settings {
+    /** Flag indicating if the system has been updated to the latest version */
     static isUpdated: boolean;
+    /** Flag controlling whether changes are synchronized online immediately */
     static isOnlineSync: boolean;
 }

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

@@ -1,4 +1,54 @@
+/**
+ * @fileoverview Defines the SigninModel interface for user authentication data.
+ * @module DataStructures/SigninModel
+ */
+/**
+ * Represents the data required for user authentication/signin.
+ * This interface defines the structure for collecting user credentials
+ * during the login process.
+ *
+ * @interface SigninModel
+ *
+ * @example
+ * ```typescript
+ * const signinData: SigninModel = {
+ *   email: "user@example.com",
+ *   password: "MySecurePassword123"
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage in an authentication function
+ * async function authenticateUser(credentials: SigninModel) {
+ *   const user = await validateCredentials(credentials.email, credentials.password);
+ *   if (user) {
+ *     return generateAuthToken(user);
+ *   }
+ *   throw new Error("Invalid credentials");
+ * }
+ * ```
+ */
 export interface SigninModel {
+    /**
+     * The user's email address.
+     * Used to identify the user account attempting to sign in.
+     *
+     * @type {string}
+     *
+     * @example "user@example.com"
+     */
     email: string;
+    /**
+     * The user's password for authentication.
+     * Will be verified against the stored hashed password.
+     *
+     * @type {string}
+     *
+     * @remarks
+     * The password is transmitted securely and verified against
+     * the hashed version stored in the database. Never store or
+     * log passwords in plain text.
+     */
     password: string;
 }

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

@@ -1,4 +1,54 @@
+/**
+ * @fileoverview Defines the SignupModel interface for user registration data.
+ * @module DataStructures/SignupModel
+ */
+/**
+ * Represents the data required for user registration/signup.
+ * This interface defines the structure for collecting user credentials
+ * during the account creation process.
+ *
+ * @interface SignupModel
+ *
+ * @example
+ * ```typescript
+ * const signupData: SignupModel = {
+ *   email: "newuser@example.com",
+ *   password: "SecureP@ssw0rd123"
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage in a signup function
+ * async function registerUser(userData: SignupModel) {
+ *   // Validate and create user account
+ *   const result = await createAccount(userData.email, userData.password);
+ *   return result;
+ * }
+ * ```
+ */
 export interface SignupModel {
+    /**
+     * The user's email address.
+     * Used as the primary identifier for the user account.
+     * Should be unique and in valid email format.
+     *
+     * @type {string}
+     *
+     * @example "user@example.com"
+     */
     email: string;
+    /**
+     * The user's password for account authentication.
+     * Should meet security requirements (e.g., minimum length, complexity).
+     * Will be hashed before storage for security purposes.
+     *
+     * @type {string}
+     *
+     * @remarks
+     * Passwords should be validated for strength before being accepted.
+     * Common requirements include minimum length, uppercase, lowercase,
+     * numbers, and special characters.
+     */
     password: string;
 }

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

@@ -1,26 +1,232 @@
+/**
+ * @fileoverview SyncData module for managing synchronization of concepts and connections in CCS-JS.
+ * This module provides queuing and batch synchronization of local changes to the backend server,
+ * with support for transactional operations and rollback capabilities.
+ * @module DataStructures/SyncData
+ */
 import { Concept } from "./Concept";
 import { Connection } from "./Connection";
 import { InnerActions } from "./Transaction/Transaction";
+/**
+ * Container for transactional sync data.
+ * Stores concepts and connections that are part of a transaction.
+ */
 type syncContainer = {
+    /** Unique transaction identifier */
     id: string;
+    /** Transaction data containing concepts and connections */
     data: InnerActions;
+    /** ISO timestamp of when the transaction was created */
     createdDate: string;
 };
+/**
+ * Manages synchronization of concepts and connections between local storage and backend.
+ * Provides queuing, batch processing, and transaction support for data synchronization.
+ *
+ * @class SyncData
+ * @example
+ * ```typescript
+ * // Add items to sync queue
+ * SyncData.AddConcept(myConcept);
+ * SyncData.AddConnection(myConnection);
+ *
+ * // Sync to backend
+ * await SyncData.SyncDataOnline();
+ *
+ * // Transaction support
+ * await SyncData.initializeTransaction("txn-123");
+ * await SyncData.markTransactionActions("txn-123", actions);
+ * await SyncData.SyncDataOnline("txn-123");
+ * ```
+ *
+ * @remarks
+ * This class provides both immediate and batched synchronization modes.
+ * Transactions are automatically cleaned up after 7 days (604800000 ms).
+ */
 export declare class SyncData {
+    /** Queue of concepts waiting to be synchronized to backend */
     static conceptsSyncArray: Concept[];
+    /** Queue of connections waiting to be synchronized to backend */
     static connectionSyncArray: Connection[];
+    /** Collection of transactional sync operations */
     static transactionCollections: syncContainer[];
+    /**
+     * Checks if a concept already exists in the sync queue.
+     *
+     * @param {Concept} concept - The concept to check
+     * @returns {boolean} True if the concept is in the sync queue, false otherwise
+     *
+     * @private
+     */
     static CheckContains(concept: Concept): boolean;
+    /**
+     * Removes all sync data related to a specific concept ID.
+     * Removes the concept and any connections that reference it.
+     *
+     * @param {number} id - The concept ID to remove from sync queues
+     *
+     * @example
+     * ```typescript
+     * SyncData.SyncDataDelete(123);
+     * ```
+     *
+     * @remarks
+     * Also removes connections where the concept appears as ofTheConceptId, toTheConceptId, or typeId.
+     */
     static SyncDataDelete(id: number): void;
+    /**
+     * Checks if a connection already exists in the sync queue.
+     *
+     * @param {Connection} connection - The connection to check
+     * @returns {boolean} True if the connection is in the sync queue, false otherwise
+     *
+     * @private
+     */
     static CheckContainsConnection(connection: Connection): boolean;
+    /**
+     * Adds a concept to the synchronization queue.
+     *
+     * @param {Concept} concept - The concept to add to sync queue
+     *
+     * @example
+     * ```typescript
+     * SyncData.AddConcept(myConcept);
+     * // Later...
+     * await SyncData.SyncDataOnline();
+     * ```
+     */
     static AddConcept(concept: Concept): void;
+    /**
+    * Removes a concept from the synchronization queue.
+    *
+    * @param {Concept} concept - The concept to remove from sync queue
+    *
+    * @example
+    * ```typescript
+    * SyncData.RemoveConcept(myConcept);
+    * ```
+    */
     static RemoveConcept(concept: Concept): void;
+    /**
+    * Adds a connection to the synchronization queue.
+    *
+    * @param {Connection} connection - The connection to add to sync queue
+    *
+    * @example
+    * ```typescript
+    * SyncData.AddConnection(myConnection);
+    * // Later...
+    * await SyncData.SyncDataOnline();
+    * ```
+    */
     static AddConnection(connection: Connection): void;
+    /**
+    * Removes a connection from the synchronization queue.
+    *
+    * @param {Connection} connection - The connection to remove from sync queue
+    *
+    * @example
+    * ```typescript
+    * SyncData.RemoveConnection(myConnection);
+    * ```
+    */
     static RemoveConnection(connection: Connection): void;
+    /**
+    * Synchronizes queued data to the backend server.
+    * Can sync either a specific transaction or all queued data.
+    *
+    * @param {string} [transactionId] - Optional transaction ID to sync specific transaction
+    * @returns {Promise<string>} Returns "done" when synchronization completes
+    * @throws {Error} If synchronization fails
+    *
+    * @example
+    * ```typescript
+    * // Sync all queued data
+    * await SyncData.SyncDataOnline();
+    *
+    * // Sync specific transaction
+    * await SyncData.SyncDataOnline("txn-123");
+    * ```
+    *
+    * @remarks
+    * - If transactionId is provided, only that transaction is synced and removed from collection
+    * - Otherwise, all queued concepts and connections are synced
+    * - Automatically cleans up transactions older than 7 days (604800000 ms)
+    * - Adds data to permanent storage before sending to backend
+    */
     static SyncDataOnline(transactionId?: string): Promise<"done" | undefined>;
+    /**
+     * Initializes a new transaction container for tracking related changes.
+     *
+     * @param {string} transactionId - Unique identifier for the transaction
+     *
+     * @example
+     * ```typescript
+     * await SyncData.initializeTransaction("txn-123");
+     * // Make changes...
+     * await SyncData.markTransactionActions("txn-123", actions);
+     * await SyncData.SyncDataOnline("txn-123");
+     * ```
+     *
+     * @remarks
+     * Does nothing if a transaction with the same ID already exists.
+     * Creates an empty container with the current timestamp.
+     */
     static initializeTransaction(transactionId: string): Promise<void>;
+    /**
+     * Marks specific actions as part of a transaction.
+     * Removes these actions from the general sync queues to prevent duplication.
+     *
+     * @param {string} transactionId - The transaction ID
+     * @param {InnerActions} actions - The concepts and connections to mark as part of transaction
+     *
+     * @example
+     * ```typescript
+     * const actions = {
+     *   concepts: [concept1, concept2],
+     *   connections: [connection1, connection2]
+     * };
+     * await SyncData.markTransactionActions("txn-123", actions);
+     * ```
+     *
+     * @remarks
+     * - Updates the transaction container with the actions
+     * - Removes marked items from conceptsSyncArray and connectionSyncArray
+     * - Matches items by both id and ghostId to handle temporary IDs
+     */
     static markTransactionActions(transactionId: string, actions: InnerActions): Promise<void>;
+    /**
+     * Rolls back a transaction by removing it from the transaction collection.
+     *
+     * @param {string} transactionId - The transaction ID to rollback
+     * @param {InnerActions} actions - The actions to rollback (currently unused)
+     *
+     * @example
+     * ```typescript
+     * await SyncData.rollbackTransaction("txn-123", actions);
+     * ```
+     *
+     * @remarks
+     * Currently only removes the transaction from collection if it doesn't already exist.
+     * The logic may need review as it checks for existence before removal.
+     */
     static rollbackTransaction(transactionId: string, actions: InnerActions): Promise<void>;
+    /**
+    * Synchronizes queued data to local IndexedDB storage only (not to backend).
+    *
+    * @returns {Promise<string>} Returns "done" when local sync completes
+    *
+    * @example
+    * ```typescript
+    * await SyncData.syncDataLocalDb();
+    * ```
+    *
+    * @remarks
+    * - Stores concepts to "localconcept" database
+    * - Stores connections to "localconnection" database
+    * - Clears the sync queues after storing
+    * - Used for offline persistence without backend sync
+    */
     static syncDataLocalDb(): Promise<string>;
 }
 export {};

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

@@ -1,13 +1,100 @@
+/**
+ * @fileoverview Character data structure for the CCS-JS system.
+ * @module DataStructures/TheCharacter
+ */
+/**
+ * Represents a character entity in the system with associated user, security, access, and session information.
+ *
+ * @remarks
+ * TheCharacter class encapsulates character data along with comprehensive metadata including
+ * user ownership, security credentials, access control, and session tracking. Each character
+ * maintains references to multiple user contexts for fine-grained authorization control.
+ *
+ * @example
+ * ```typescript
+ * const character = new TheCharacter(
+ *   1001,                    // userId
+ *   "A",                     // data
+ *   5001,                    // securityId
+ *   1001,                    // securityUserId
+ *   6001,                    // accessId
+ *   1001,                    // accessUserId
+ *   7001,                    // sessionId
+ *   1001,                    // sessionUserId
+ *   "2025-10-30T12:00:00Z",  // entryTimestamp
+ *   true                     // isNew
+ * );
+ * ```
+ */
 export declare class TheCharacter {
+    /**
+     * Unique identifier for the character.
+     * @defaultValue 0
+     */
     id: number;
+    /**
+     * ID of the user who owns this character.
+     */
     userId: number;
+    /**
+     * The actual character data (typically a single character string).
+     */
     data: string;
+    /**
+     * Security level or security context identifier for this character.
+     */
     securityId: number;
+    /**
+     * User ID associated with the security context.
+     */
     securityUserId: number;
+    /**
+     * Access control identifier for this character.
+     */
     accessId: number;
+    /**
+     * User ID associated with the access control.
+     */
     accessUserId: number;
+    /**
+     * Session identifier tracking when this character was accessed.
+     */
     sessionId: number;
+    /**
+     * User ID associated with the session.
+     */
     sessionUserId: number;
+    /**
+     * Flag indicating whether this is a newly created character.
+     * @defaultValue false
+     */
     isNew: boolean;
+    /**
+     * Creates a new TheCharacter instance.
+     *
+     * @param userId - The ID of the user who owns this character
+     * @param data - The character data (will be converted to string)
+     * @param securityId - Security level or context identifier
+     * @param securityUserId - User ID for the security context
+     * @param accessId - Access control identifier
+     * @param accessUserId - User ID for access control
+     * @param sessionId - Session tracking identifier
+     * @param sessionUserId - User ID for the session
+     * @param entryTimestamp - Timestamp when the character was created/entered (currently unused in initialization)
+     * @param isNew - Whether this is a newly created character
+     *
+     * @remarks
+     * The data parameter is explicitly converted to a string using template literals.
+     * The entryTimestamp parameter is accepted but not currently stored in the instance.
+     *
+     * @example
+     * ```typescript
+     * const char = new TheCharacter(
+     *   1, "X", 100, 1, 200, 1, 300, 1, "2025-10-30", true
+     * );
+     * console.log(char.data); // "X"
+     * console.log(char.isNew); // true
+     * ```
+     */
     constructor(userId: number, data: string, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionId: number, sessionUserId: number, entryTimestamp: string, isNew: boolean);
 }