mftsccs-node 0.2.7 → 0.2.8

package/dist/types/Api/Search/SearchInternalApi.d.ts

@@ -1,2 +1,71 @@
+/**
+ * Internal Search API module for querying concepts within nested compositions.
+ * This module provides specialized search functionality for searching concepts that exist
+ * within internal (nested) compositions, enabling hierarchical concept retrieval in the
+ * Concept Connection System.
+ *
+ * @module Api/Search/SearchInternalApi
+ * @see https://documentation.freeschema.com for internal composition structure and search patterns
+ */
 import { SearchStructure } from "../../app";
+/**
+ * Searches for concepts within internal (nested) compositions with authentication.
+ * This function enables searching for concepts that are part of internal compositions,
+ * which are compositions nested within other compositions. It performs a GET request
+ * with query parameters to search both the parent composition and internal composition.
+ *
+ * @param search - SearchStructure object containing all search parameters including composition, internal composition, type, search text, and pagination
+ * @param token - Optional authentication token for authorized access (defaults to empty string for public queries)
+ * @returns Promise resolving to an array of matching concepts from the internal composition, or empty array on error
+ *
+ * @example
+ * ```typescript
+ * // Search for concepts in an internal composition
+ * const searchParams: SearchStructure = {
+ *   composition: "parent-composition-123",
+ *   internalComposition: "nested-composition-456",
+ *   type: "Task",
+ *   search: "urgent",
+ *   inpage: 15,
+ *   page: 1
+ * };
+ * const results = await SearchInternalApi(searchParams, "auth-token-789");
+ * console.log(`Found ${results.length} urgent tasks in nested composition`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Search in a deeply nested composition structure
+ * const searchParams: SearchStructure = {
+ *   composition: "organization",
+ *   internalComposition: "department.team.projects",
+ *   type: "Project",
+ *   search: "active",
+ *   inpage: 10,
+ *   page: 1
+ * };
+ * const activeProjects = await SearchInternalApi(searchParams, authToken);
+ * ```
+ *
+ * @remarks
+ * This function is specifically designed for hierarchical concept structures where
+ * compositions can contain other compositions. It's particularly useful for:
+ * - Searching within organizational hierarchies
+ * - Querying nested data structures
+ * - Accessing concepts in private or protected sub-compositions
+ * - Filtering results within specific composition contexts
+ *
+ * Error handling:
+ * - HTTP errors are logged with status and handled via HandleHttpError
+ * - Network errors are caught, logged, and re-thrown
+ * - Returns empty array on HTTP errors to prevent null reference issues
+ *
+ * Query construction:
+ * - All parameters are URL-encoded as query strings
+ * - The URL pattern: ?composition=X&search=Y&internalComposition=Z&type=T&inpage=N&page=P
+ * - Uses authenticated CCS endpoint for secure access
+ *
+ * @see SearchAllConcepts for searching in top-level compositions
+ * @see FreeschemaQueryApi for complex nested queries
+ */
 export declare function SearchInternalApi(search: SearchStructure, token?: string): Promise<any>;

package/dist/types/Api/Search/SearchLinkMultipleApi.d.ts

@@ -1,2 +1,92 @@
+/**
+ * Search Link Multiple API module for executing batch searches across multiple queries.
+ * This module provides functionality to search for concepts using multiple search queries
+ * in a single API call, optimizing performance for applications that need to retrieve
+ * related or linked concepts efficiently.
+ *
+ * @module Api/Search/SearchLinkMultipleApi
+ * @see https://documentation.freeschema.com for batch search patterns and optimization techniques
+ */
 import { SearchQuery } from '../../DataStructures/SearchQuery';
+/**
+ * Executes multiple search queries in a single API call to retrieve linked concepts.
+ * This function sends an array of SearchQuery objects to the backend, which processes
+ * all queries and returns the combined results. This is significantly more efficient
+ * than making individual API calls for each query, especially when searching for
+ * related or linked concepts.
+ *
+ * @param searchQuery - Array of SearchQuery objects, each containing search parameters for a specific query
+ * @param token - Optional authentication token for authorized access (defaults to empty string for public queries)
+ * @returns Promise resolving to an array of search results (one result set per query), or empty array on error
+ *
+ * @example
+ * ```typescript
+ * // Search for multiple related concepts simultaneously
+ * const queries: SearchQuery[] = [
+ *   {
+ *     type: "Person",
+ *     search: "John",
+ *     composition: "users",
+ *     inpage: 10,
+ *     page: 1
+ *   },
+ *   {
+ *     type: "Organization",
+ *     search: "Company",
+ *     composition: "organizations",
+ *     inpage: 5,
+ *     page: 1
+ *   },
+ *   {
+ *     type: "Document",
+ *     search: "contract",
+ *     composition: "documents",
+ *     inpage: 20,
+ *     page: 1
+ *   }
+ * ];
+ * const results = await SearchLinkMultipleApi(queries, "auth-token-123");
+ * console.log(`Retrieved ${results.length} result sets`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Search for a person and their associated data in one call
+ * const linkedQueries: SearchQuery[] = [
+ *   { type: "Person", search: "Alice", composition: "main", inpage: 1, page: 1 },
+ *   { type: "Post", search: "Alice", composition: "social", inpage: 10, page: 1 },
+ *   { type: "Comment", search: "Alice", composition: "social", inpage: 10, page: 1 }
+ * ];
+ * const [person, posts, comments] = await SearchLinkMultipleApi(linkedQueries, token);
+ * ```
+ *
+ * @remarks
+ * This function is optimized for scenarios where you need to:
+ * - Retrieve multiple related concepts in a single request
+ * - Reduce network round-trips and improve performance
+ * - Maintain consistency across related queries (all executed at the same time)
+ * - Search for linked or connected concepts efficiently
+ *
+ * Performance benefits:
+ * - Single HTTP connection instead of multiple
+ * - Reduced network latency
+ * - Server-side query optimization
+ * - Atomic execution of all queries
+ *
+ * Error handling:
+ * - HTTP errors are logged with status and handled via HandleHttpError
+ * - Network errors are caught, logged, and re-thrown
+ * - Returns empty array on HTTP errors to prevent null reference issues
+ * - If any query fails, the entire operation returns an empty array
+ *
+ * Query execution:
+ * - All queries are executed server-side
+ * - Results maintain the same order as input queries
+ * - Each query can have different pagination settings
+ * - Each query is independent but executed atomically
+ *
+ * @see SearchWithLinker for alternative batch search with linker functionality
+ * @see SearchAllConcepts for single concept searches
+ * @see FreeschemaQueryApi for complex queries
+ */
 export declare function SearchLinkMultipleApi(searchQuery: SearchQuery[], token?: string): Promise<any>;

package/dist/types/Api/Search/SearchWithLinker.d.ts

@@ -1,2 +1,99 @@
+/**
+ * Search With Linker API module for executing linked searches across related concepts.
+ * This module provides functionality to search for concepts with automatic link resolution,
+ * enabling efficient retrieval of connected concepts and their relationships in the
+ * Concept Connection System. The linker functionality automatically resolves and includes
+ * related concepts based on defined relationships.
+ *
+ * @module Api/Search/SearchWithLinker
+ * @see https://documentation.freeschema.com for linker patterns and relationship traversal
+ */
 import { SearchQuery } from '../../DataStructures/SearchQuery';
+/**
+ * Executes multiple search queries with automatic link resolution and relationship traversal.
+ * This function searches for concepts while automatically resolving and including linked
+ * concepts based on defined relationships. The linker functionality intelligently follows
+ * concept connections, providing a complete view of related data in a single API call.
+ *
+ * @param searchQuery - Array of SearchQuery objects defining search criteria and relationship paths to follow
+ * @param token - Optional authentication token for authorized access (defaults to empty string for public queries)
+ * @returns Promise resolving to an array of search results with linked concepts resolved, or empty array on error
+ *
+ * @example
+ * ```typescript
+ * // Search for a person and automatically include their related concepts
+ * const queries: SearchQuery[] = [
+ *   {
+ *     type: "Person",
+ *     search: "John Doe",
+ *     composition: "users",
+ *     inpage: 1,
+ *     page: 1
+ *   }
+ * ];
+ * // The linker will automatically include related organizations, posts, etc.
+ * const results = await SearchWithLinker(queries, "auth-token-123");
+ * console.log("Person with all linked data:", results);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Search for multiple concepts with link resolution
+ * const queries: SearchQuery[] = [
+ *   {
+ *     type: "Project",
+ *     search: "Alpha",
+ *     composition: "projects",
+ *     inpage: 5,
+ *     page: 1
+ *   },
+ *   {
+ *     type: "Team",
+ *     search: "Engineering",
+ *     composition: "teams",
+ *     inpage: 5,
+ *     page: 1
+ *   }
+ * ];
+ * // Results will include projects with linked tasks, team members, etc.
+ * const linkedResults = await SearchWithLinker(queries, token);
+ * ```
+ *
+ * @remarks
+ * The SearchWithLinker function differs from SearchLinkMultipleApi by automatically
+ * resolving concept relationships and including linked concepts in the results.
+ * This is particularly useful for:
+ * - Retrieving complete object graphs in one call
+ * - Following relationship chains automatically
+ * - Reducing the need for multiple follow-up queries
+ * - Building comprehensive views of related data
+ *
+ * Link resolution behavior:
+ * - Automatically follows defined relationships between concepts
+ * - Includes linked concepts in the response
+ * - Respects composition boundaries and access controls
+ * - Optimizes server-side to prevent N+1 query problems
+ *
+ * Performance considerations:
+ * - More comprehensive than simple searches but single round-trip
+ * - Server-side optimization for relationship traversal
+ * - May return larger payloads due to included linked concepts
+ * - Ideal for reducing client-side data fetching complexity
+ *
+ * Error handling:
+ * - HTTP errors are logged with status and handled via HandleHttpError
+ * - Network errors are caught, logged, and re-thrown
+ * - Returns empty array on HTTP errors to maintain consistent error handling
+ * - Link resolution errors are handled gracefully server-side
+ *
+ * Use cases:
+ * - Building detailed profile views with all related data
+ * - Dashboard displays requiring multiple related entities
+ * - Report generation needing complete relationship graphs
+ * - Mobile applications minimizing network requests
+ *
+ * @see SearchLinkMultipleApi for batch searches without automatic link resolution
+ * @see SearchAllConcepts for simple single-concept searches
+ * @see FreeschemaQueryApi for custom relationship queries
+ */
 export declare function SearchWithLinker(searchQuery: SearchQuery[], token?: string): Promise<any>;

package/dist/types/Api/SearchConcept/GetConceptByCharacterAndCategoryApi.d.ts

@@ -1,2 +1,41 @@
+/**
+ * API module for searching concepts by their character value and category.
+ * Retrieves concepts from the backend based on their character representation.
+ *
+ * @module Api/SearchConcept/GetConceptByCharacterAndCategoryApi
+ * @see https://documentation.freeschema.com for reference
+ */
 import { Concept } from "../../DataStructures/Concept";
+/**
+ * Retrieves a concept from the backend by its character value.
+ * The character value is a string representation that uniquely identifies a concept.
+ *
+ * This function queries the backend for a concept matching the provided character value,
+ * automatically determining the appropriate category. Retrieved concepts are added to
+ * the local ConceptsData cache for faster subsequent access.
+ *
+ * @param characterValue - The character string identifying the concept (e.g., "the_person", "john_doe")
+ * @returns A promise that resolves to the matching Concept object, or a default concept if not found
+ *
+ * @example
+ * ```typescript
+ * // Find a concept by its character value
+ * const concept = await GetConceptByCharacterAndCategoryApi('the_person');
+ * if (concept.id !== 0) {
+ *   console.log('Found concept:', concept.characterValue);
+ * } else {
+ *   console.log('Concept not found');
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns a default concept (id=0) if the concept is not found or an error occurs
+ * - Automatically caches the retrieved concept in ConceptsData
+ * - HTTP errors are handled through HandleHttpError but do not throw
+ * - Errors are logged to console and re-thrown for caller handling
+ *
+ * @see GetConceptByCharacterAndCategoryDirectApi for searching with explicit category
+ * @see CreateDefaultConcept for the default concept structure
+ * @see ConceptsData for the local concept cache
+ */
 export declare function GetConceptByCharacterAndCategoryApi(characterValue: string): Promise<Concept>;

package/dist/types/Api/SearchConcept/GetConceptByCharacterAndCategoryDirect.d.ts

@@ -1,2 +1,49 @@
+/**
+ * API module for searching concepts by character value with explicit category specification.
+ * Provides direct category-based concept retrieval with request caching.
+ *
+ * @module Api/SearchConcept/GetConceptByCharacterAndCategoryDirect
+ * @see https://documentation.freeschema.com for reference
+ */
 import { Concept } from "./../../DataStructures/Concept";
+/**
+ * Retrieves a concept from the backend by its character value and specific category ID.
+ * This is a more precise search than GetConceptByCharacterAndCategoryApi as it requires
+ * an explicit category ID.
+ *
+ * The function uses request caching to prevent duplicate simultaneous requests for the
+ * same character-category combination. Retrieved concepts are automatically added to
+ * the local ConceptsData cache.
+ *
+ * @param characterValue - The character string identifying the concept (e.g., "john_doe", "building_a")
+ * @param category_id - The specific category ID to search within
+ * @returns A promise that resolves to the matching Concept object, or a default concept if not found
+ *
+ * @example
+ * ```typescript
+ * // Find a specific person concept in category 5
+ * const person = await GetConceptByCharacterAndCategoryDirectApi('john_doe', 5);
+ * if (person.id !== 0) {
+ *   console.log('Found person:', person);
+ * }
+ *
+ * // Simultaneous calls for the same concept will use the same cached promise
+ * const promise1 = GetConceptByCharacterAndCategoryDirectApi('jane_doe', 5);
+ * const promise2 = GetConceptByCharacterAndCategoryDirectApi('jane_doe', 5);
+ * // Both will resolve to the same result without making duplicate API calls
+ * ```
+ *
+ * @remarks
+ * - Uses local caching (conceptCache) to prevent duplicate simultaneous requests
+ * - Cache key is the concatenation of characterValue and category_id
+ * - Returns a default concept (id=0) if the concept is not found or an error occurs
+ * - Automatically caches the retrieved concept in ConceptsData for subsequent use
+ * - Cache entries are cleaned up in the finally block after fetch completes
+ * - HTTP errors are handled through HandleHttpError but do not throw
+ * - Errors are logged with full diagnostic information including the endpoint URL
+ *
+ * @see GetConceptByCharacterAndCategoryApi for searching without explicit category
+ * @see CreateDefaultConcept for the default concept structure
+ * @see ConceptsData for the local concept cache
+ */
 export declare function GetConceptByCharacterAndCategoryDirectApi(characterValue: string, category_id: number): Promise<Concept>;

package/dist/types/Api/Session/CreateSession.d.ts

@@ -1,2 +1,47 @@
+/**
+ * API module for creating user session records.
+ * Tracks user sessions for analytics and activity monitoring purposes.
+ *
+ * @module Api/Session/CreateSession
+ * @see https://documentation.freeschema.com for reference
+ */
 import { SessionData } from "../../app";
+/**
+ * Creates a new session record in the backend for tracking user activity.
+ * Sessions are used to monitor user interactions, track analytics, and maintain
+ * activity logs within the Concept Connection System.
+ *
+ * This function initiates a new session with the provided session data, which
+ * typically includes user information, timestamps, and session metadata.
+ *
+ * @param sessionData - The session data object containing session initialization information
+ * @returns A promise that resolves to the created session response, or null if creation fails
+ *
+ * @example
+ * ```typescript
+ * // Create a new user session
+ * const sessionInfo: SessionData = {
+ *   userId: 123,
+ *   startTime: new Date().toISOString(),
+ *   userAgent: navigator.userAgent
+ * };
+ *
+ * const session = await CreateSession(sessionInfo);
+ * if (session) {
+ *   console.log('Session created:', session.sessionId);
+ * } else {
+ *   console.log('Session creation failed');
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns null if the session creation fails
+ * - HTTP errors are handled through HandleHttpError
+ * - Requires authentication via GetRequestHeader
+ * - Error details are logged to console for debugging
+ * - Errors are re-thrown for caller handling
+ *
+ * @see CreateSessionVisit for tracking URL visits within a session
+ * @see SessionData for the session data structure
+ */
 export declare function CreateSession(sessionData: SessionData): Promise<any>;

package/dist/types/Api/Session/CreateSessionVisit.d.ts

@@ -1 +1,44 @@
+/**
+ * API module for tracking URL visits within user sessions.
+ * Records individual page/URL visits as part of session activity tracking.
+ *
+ * @module Api/Session/CreateSessionVisit
+ * @see https://documentation.freeschema.com for reference
+ */
+/**
+ * Records a URL visit within an existing session for activity tracking.
+ * This function creates a session visit record that tracks which URLs a user
+ * accesses during their session, useful for analytics and navigation tracking.
+ *
+ * Session visits help build a complete picture of user activity by recording
+ * each page or resource accessed during a session in the Concept Connection System.
+ *
+ * @param sessionId - The unique identifier of the session to associate this visit with
+ * @param url - The URL that was visited (page path or full URL)
+ * @returns A promise that resolves to the created visit response, or null if creation fails
+ *
+ * @example
+ * ```typescript
+ * // Track a page visit within a session
+ * const visit = await CreateSessionVisit(456, '/concepts/dashboard');
+ * if (visit) {
+ *   console.log('Visit tracked:', visit);
+ * }
+ *
+ * // Track multiple visits in sequence
+ * await CreateSessionVisit(456, '/concepts/search');
+ * await CreateSessionVisit(456, '/concepts/create');
+ * await CreateSessionVisit(456, '/concepts/view/123');
+ * ```
+ *
+ * @remarks
+ * - Returns null if the visit creation fails
+ * - HTTP errors are handled through HandleHttpError
+ * - Requires authentication via GetRequestHeader
+ * - Uses URL-encoded form data for the request body
+ * - Error details are logged to console for debugging
+ * - Errors are re-thrown for caller handling
+ *
+ * @see CreateSession for creating the initial session
+ */
 export declare function CreateSessionVisit(sessionId: number, url: string): Promise<any>;

package/dist/types/Api/Signin.d.ts

@@ -1,3 +1,51 @@
+/**
+ * API module for user sign-in operations.
+ * Provides standardized authentication with structured response handling.
+ *
+ * @module Api/Signin
+ * @see https://documentation.freeschema.com for reference
+ */
 import { FreeschemaResponse } from "../DataStructures/Responses/StandardResponses";
 import { SigninModel } from "../DataStructures/SigninModel";
+/**
+ * Authenticates a user and returns a standardized Freeschema response.
+ * This function provides a more structured authentication approach compared to LoginToBackend,
+ * returning a FreeschemaResponse object with consistent status and data fields.
+ *
+ * The signin process validates user credentials and returns authentication data including
+ * tokens and user information in a standardized response format.
+ *
+ * @param signinInfo - The signin model containing user credentials (email and password)
+ * @returns A promise that resolves to a FreeschemaResponse containing authentication data
+ *
+ * @example
+ * ```typescript
+ * // Sign in a user with standardized response
+ * const signinData: SigninModel = {
+ *   email: 'user@example.com',
+ *   password: 'securePassword123'
+ * };
+ *
+ * const response = await Signin(signinData);
+ * if (response.status && response.statusCode === 200) {
+ *   console.log('Signin successful:', response.data);
+ *   // Use response.data.token for subsequent API calls
+ * } else {
+ *   console.error('Signin failed:', response.message);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns a FreeschemaResponse with status, statusCode, message, and data fields
+ * - On success: status=true, statusCode=200, data contains authentication information
+ * - On failure: status=false, statusCode and message indicate the error
+ * - HTTP errors are handled through HandleHttpError
+ * - Errors are logged to console and re-thrown for caller handling
+ * - Uses JSON content-type for request body
+ *
+ * @see LoginToBackend for alternative login implementation
+ * @see Signup for user registration
+ * @see SigninModel for the signin data structure
+ * @see FreeschemaResponse for the response structure
+ */
 export default function Signin(signinInfo: SigninModel): Promise<FreeschemaResponse>;

package/dist/types/Api/Signup.d.ts

@@ -1,3 +1,47 @@
+/**
+ * API module for user registration and signup operations.
+ * Handles new user account creation with standardized response handling.
+ *
+ * @module Api/Signup
+ * @see https://documentation.freeschema.com for reference
+ */
 import { FreeschemaResponse } from "../DataStructures/Responses/StandardResponses";
 import { SignupModel } from "../DataStructures/SignupModel";
+/**
+ * Registers a new user account in the Concept Connection System.
+ * This function creates a new user with the provided signup information and returns
+ * a standardized response containing registration results.
+ *
+ * @param signupModel - The signup model containing user registration information (name, email, password, etc.)
+ * @returns A promise that resolves to a FreeschemaResponse indicating success or failure
+ *
+ * @example
+ * ```typescript
+ * // Register a new user
+ * const newUser: SignupModel = {
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   password: 'securePassword123'
+ * };
+ *
+ * const response = await Signup(newUser);
+ * if (response.status && response.statusCode === 200) {
+ *   console.log('Signup successful:', response.data);
+ * } else {
+ *   console.error('Signup failed:', response.message);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns a FreeschemaResponse with status, statusCode, message, and data fields
+ * - On success: status=true, statusCode=200, data contains user information
+ * - On failure: status=false with error details
+ * - HTTP errors are handled through HandleHttpError
+ * - Errors are logged to console and re-thrown for caller handling
+ *
+ * @see Signin for user authentication after signup
+ * @see LoginToBackend for alternative login
+ * @see SignupModel for the signup data structure
+ * @see FreeschemaResponse for the response structure
+ */
 export default function Signup(signupModel: SignupModel): Promise<FreeschemaResponse>;

package/dist/types/Api/View/ViewInternalDataApi.d.ts

@@ -1 +1,51 @@
+/**
+ * API module for viewing internal concept data and connections.
+ * Retrieves detailed internal structure including connections for specified concepts.
+ *
+ * @module Api/View/ViewInternalDataApi
+ * @see https://documentation.freeschema.com for reference
+ */
+/**
+ * Retrieves internal data and connections for a list of concept IDs.
+ * This function fetches the internal composition structure of concepts, including all
+ * sub-concepts and their interconnections, providing a complete view of concept internals.
+ *
+ * In the Concept Connection System, concepts can contain other concepts as part of their
+ * internal structure (composition). This function retrieves those internal concepts and
+ * the connections between them, returning a dictionary mapping concept IDs to their
+ * internal connection lists.
+ *
+ * @param ids - Array of concept IDs to retrieve internal data for
+ * @returns A promise that resolves to a dictionary mapping concept IDs to their internal connections,
+ *          or an empty connection list if the request fails
+ *
+ * @example
+ * ```typescript
+ * // View internal data for multiple concepts
+ * const conceptIds = [100, 101, 102];
+ * const internalData = await ViewInternalDataApi(conceptIds);
+ *
+ * // Access connections for a specific concept
+ * const concept100Connections = internalData[100];
+ * if (concept100Connections) {
+ *   console.log('Concept 100 has', concept100Connections.length, 'internal connections');
+ * }
+ *
+ * // Process all internal structures
+ * for (const [conceptId, connections] of Object.entries(internalData)) {
+ *   console.log(`Concept ${conceptId}:`, connections);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns an object where keys are concept IDs and values are arrays of Connection objects
+ * - Automatically fetches and caches all sub-concepts via GetConceptBulk
+ * - Returns an empty connection list on error
+ * - HTTP errors are handled through HandleHttpError but do not throw
+ * - Requires authentication via GetRequestHeader
+ * - Errors are logged to console and re-thrown for caller handling
+ *
+ * @see GetConceptBulk for bulk concept retrieval
+ * @see Connection for the connection data structure
+ */
 export declare function ViewInternalDataApi(ids: number[]): Promise<any>;