mftsccs-node 0.0.56 → 0.0.58

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

@@ -0,0 +1,37 @@
+/**
+ * API module for fetching reserved connection IDs from the backend.
+ * Manages a pool of pre-allocated connection IDs to optimize performance when creating connections.
+ *
+ * @module Api/GetReservedConnectionIds
+ * @see https://documentation.freeschema.com for reference
+ */
+/**
+ * Fetches reserved connection IDs from the backend and stores them in the local pool.
+ * Uses a queue-based system to prevent simultaneous requests and maintains a minimum
+ * threshold of available IDs.
+ *
+ * This function is critical for maintaining a pool of pre-allocated connection IDs,
+ * which improves performance by avoiding the need to request IDs individually when
+ * creating new connections in the Concept Connection System.
+ *
+ * @returns A promise that resolves when the IDs are successfully fetched and stored
+ *
+ * @example
+ * ```typescript
+ * // Ensure reserved connection IDs are available
+ * await GetReservedConnectionIds();
+ *
+ * // Now IDs can be consumed from ReservedConnectionIds.connectionIds
+ * const id = ReservedConnectionIds.GetId();
+ * ```
+ *
+ * @remarks
+ * - Skips fetching if more than 10 IDs are already available
+ * - Uses a queue system to serialize requests and prevent concurrent fetches
+ * - Automatically refills the pool when it runs low
+ * - Errors are logged but the promise is rejected to allow proper error handling
+ *
+ * @see ReservedConnectionIds for the storage data structure
+ * @see GetReservedIds for fetching regular concept IDs
+ */
+export declare function GetReservedConnectionIds(): Promise<void>;

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

@@ -0,0 +1,38 @@
+/**
+ * API module for fetching reserved concept IDs from the backend.
+ * Manages a pool of pre-allocated concept IDs to optimize performance when creating new concepts.
+ *
+ * @module Api/GetReservedIds
+ * @see https://documentation.freeschema.com for reference
+ */
+/**
+ * Fetches reserved concept IDs from the backend and stores them in the local pool.
+ * Uses a queue-based system to prevent simultaneous requests and maintains a minimum
+ * threshold of available IDs.
+ *
+ * This function is essential for maintaining a pool of pre-allocated concept IDs,
+ * which significantly improves performance by avoiding the need to request IDs
+ * individually when creating new concepts in the Concept Connection System.
+ *
+ * @returns A promise that resolves when the IDs are successfully fetched and stored
+ *
+ * @example
+ * ```typescript
+ * // Ensure reserved concept IDs are available
+ * await GetReservedIds();
+ *
+ * // Now IDs can be consumed from ReservedIds.ids
+ * const id = ReservedIds.GetId();
+ * ```
+ *
+ * @remarks
+ * - Skips fetching if more than 10 IDs are already available
+ * - Uses a queue system to serialize requests and prevent concurrent fetches
+ * - Automatically refills the pool when it runs low during concept creation
+ * - Errors are logged with the endpoint URL for debugging purposes
+ * - The promise is rejected on error to allow proper error handling
+ *
+ * @see ReservedIds for the storage data structure
+ * @see GetReservedConnectionIds for fetching connection IDs
+ */
+export declare function GetReservedIds(): Promise<void>;

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

@@ -0,0 +1,39 @@
+/**
+ * API module for user authentication and login functionality.
+ * Handles user login by validating credentials against the backend and storing the access token.
+ *
+ * @module Api/Login
+ * @see https://documentation.freeschema.com for reference
+ */
+/**
+ * Authenticates a user with the backend using email and password credentials.
+ * Upon successful authentication, stores the bearer access token for subsequent API requests.
+ *
+ * This function is used for logging existing users into the Concept Connection System,
+ * enabling them to perform authenticated operations such as creating and modifying concepts.
+ *
+ * @param email - The user's email address used for authentication
+ * @param password - The user's password for authentication
+ * @returns A promise that resolves to the login response containing user data and token, or undefined on error
+ *
+ * @example
+ * ```typescript
+ * // Login an existing user
+ * const result = await LoginToBackend('user@example.com', 'securePassword123');
+ * if (result) {
+ *   console.log('Login successful:', result.data);
+ *   // Token is automatically stored in TokenStorage.BearerAccessToken
+ * }
+ * ```
+ *
+ * @remarks
+ * - The bearer access token is automatically stored in TokenStorage.BearerAccessToken upon successful login
+ * - HTTP errors are handled through HandleHttpError for consistent error reporting
+ * - The function returns undefined if the response is not OK
+ * - Errors are logged to console and re-thrown for caller handling
+ *
+ * @see Signin for an alternative login implementation
+ * @see Signup for user registration
+ * @see TokenStorage for token management
+ */
+export declare function LoginToBackend(email: string, password: string): Promise<any>;

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

@@ -0,0 +1,40 @@
+/**
+ * API module for creating named concept entries in the backend.
+ * Registers concept names (referents) with their associated type information in the system.
+ *
+ * @module Api/MakeTheNameInBackend
+ * @see https://documentation.freeschema.com for reference
+ */
+/**
+ * Creates a named concept entry in the backend by associating a referent (name) with a concept ID.
+ * This function registers the human-readable name for a concept along with its type classification.
+ *
+ * In the Concept Connection System, concepts are identified by numeric IDs, but they also need
+ * human-readable names (referents). This function establishes that association in the backend.
+ *
+ * @param newConceptId - The unique identifier of the concept being named
+ * @param referent - The human-readable name or label for the concept
+ * @param typeId - The type category ID that classifies this concept
+ * @param typeUserId - The user ID associated with the type
+ * @returns A promise that resolves when the name is successfully registered
+ *
+ * @example
+ * ```typescript
+ * // Create a named concept for "John Doe" as a person type
+ * await MakeTheNameInBackend(
+ *   12345,           // newConceptId
+ *   'John Doe',      // referent
+ *   999,             // typeId for 'person'
+ *   1                // typeUserId
+ * );
+ * ```
+ *
+ * @remarks
+ * - This function does not return a value on success, only throws on error
+ * - HTTP errors are handled through HandleHttpError
+ * - Requires authentication via GetRequestHeader
+ * - Errors are logged and re-thrown for caller handling
+ *
+ * @see MakeTheTypeConceptApi for creating type concepts
+ */
+export declare function MakeTheNameInBackend(newConceptId: number, referent: string, typeId: number, typeUserId: number): Promise<void>;

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

@@ -0,0 +1,42 @@
+/**
+ * API module for creating and retrieving type concepts.
+ * Type concepts define the categories and classifications used in the Concept Connection System.
+ *
+ * @module Api/MakeTheTypeConceptApi
+ * @see https://documentation.freeschema.com for reference
+ */
+import { Concept } from "../DataStructures/Concept";
+/**
+ * Retrieves or creates a type concept based on a string identifier.
+ * Type concepts are special concepts that define categories for other concepts in the system.
+ *
+ * This function first attempts to find an existing type concept locally, then queries the backend
+ * if not found. If the concept doesn't exist in the backend, it creates a new type concept.
+ * The function uses caching to prevent duplicate requests for the same type.
+ *
+ * @param type - The string identifier for the type concept (e.g., "the_person", "the_location")
+ * @param userId - The user ID associated with the request
+ * @returns A promise that resolves to the Concept object representing the type
+ *
+ * @example
+ * ```typescript
+ * // Get or create a "person" type concept
+ * const personType = await MakeTheTypeConceptApi('the_person', 123);
+ * console.log('Person type ID:', personType.id);
+ *
+ * // Use the type concept when creating new concepts
+ * const newPerson = await CreateConcept('John Doe', personType.id);
+ * ```
+ *
+ * @remarks
+ * - Uses local caching to prevent duplicate simultaneous requests
+ * - First searches for existing concept via GetConceptByCharacterAndCategory
+ * - Creates new type concept in backend if not found or if typeId is 4 (unknown type)
+ * - Automatically adds the retrieved concept to ConceptsData for local access
+ * - Cache entries are cleaned up after the fetch completes
+ * - Returns a default concept with id=0 if errors occur
+ *
+ * @see GetConceptByCharacterAndCategory for local concept searching
+ * @see MakeTheNameInBackend for creating named concepts
+ */
+export declare function MakeTheTypeConceptApi(type: string, userId: number): Promise<Concept>;

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

@@ -0,0 +1,44 @@
+/**
+ * API module for performing recursive searches through concept compositions.
+ * Enables complex queries that traverse concept relationships and compositions.
+ *
+ * @module Api/RecursiveSearch
+ * @see https://documentation.freeschema.com for reference
+ */
+/**
+ * Performs a recursive search through concept compositions using specified filters.
+ * This function searches through the network of concepts, following composition relationships
+ * and filtering by linker types and text content.
+ *
+ * Recursive search is a powerful feature of the Concept Connection System that allows
+ * navigation through complex concept hierarchies. It can find all concepts within a composition,
+ * filtered by specific relationship types (linkers) and text search terms.
+ *
+ * @param composition - The composition ID to search within (0 for global search)
+ * @param listLinkers - Array of linker type strings to filter connections (e.g., ['is_a', 'has_property'])
+ * @param textSearch - Text string to search for within concept names/properties
+ * @returns A promise that resolves to an array of concepts matching the search criteria
+ *
+ * @example
+ * ```typescript
+ * // Search for all concepts within composition 100 that have 'is_a' relationships
+ * const results = await RecursiveSearchApi(100, ['is_a']);
+ *
+ * // Search for concepts containing "person" in composition 200
+ * const personResults = await RecursiveSearchApi(200, [], 'person');
+ *
+ * // Combined search with linkers and text
+ * const filtered = await RecursiveSearchApi(300, ['has_property', 'located_at'], 'building');
+ * ```
+ *
+ * @remarks
+ * - Returns an empty array if the search fails or no results are found
+ * - The function retrieves both internal and external connections
+ * - Results are processed through GetCompositionFromConnectionsWithDataId to build full concept objects
+ * - HTTP errors are handled through HandleHttpError
+ * - Errors are logged and re-thrown for caller handling
+ *
+ * @see SearchQuery for the query data structure
+ * @see GetCompositionFromConnectionsWithDataId for result processing
+ */
+export declare function RecursiveSearchApi(composition?: number, listLinkers?: string[], textSearch?: string): Promise<any[]>;

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

@@ -0,0 +1,48 @@
+/**
+ * Freeschema Query API module for executing flexible schema-based queries.
+ * This module provides functionality to query concepts using the Freeschema query language,
+ * which allows for dynamic and flexible data retrieval from the Concept Connection System.
+ *
+ * @module Api/Search/FreeschemaQueryApi
+ * @see https://documentation.freeschema.com for Freeschema query syntax and examples
+ */
+import { FreeschemaQuery } from "../../DataStructures/Search/FreeschemaQuery";
+/**
+ * Executes a Freeschema query to retrieve concepts from the CCS backend.
+ * This function sends a POST request with a FreeschemaQuery object to perform
+ * flexible, schema-independent queries on the concept database. The Freeschema
+ * query language enables complex filtering, nested searches, and dynamic property
+ * access across different concept types.
+ *
+ * @param query - The FreeschemaQuery object containing query parameters, filters, and search criteria
+ * @param token - Optional authentication token for authorized access (defaults to empty string for public queries)
+ * @returns Promise resolving to an array of matching concepts, or empty array on error
+ *
+ * @example
+ * ```typescript
+ * // Search for concepts with specific properties
+ * const query: FreeschemaQuery = {
+ *   type: "Person",
+ *   filters: { age: { $gt: 18 } },
+ *   limit: 10
+ * };
+ * const results = await FreeschemaQueryApi(query, "auth-token-123");
+ * console.log(`Found ${results.length} matching concepts`);
+ * ```
+ *
+ * @remarks
+ * This function handles both HTTP errors and internal exceptions gracefully:
+ * - HTTP errors are logged and handled via HandleHttpError
+ * - Internal errors are caught and reported via HandleInternalError
+ * - Returns empty array on any failure to prevent null reference errors
+ *
+ * The Freeschema query system is particularly useful for:
+ * - Cross-composition searches
+ * - Dynamic property filtering
+ * - Complex relationship traversal
+ * - Type-independent queries
+ *
+ * @see SearchAllConcepts for simpler search operations
+ * @see SearchWithLinker for linked concept searches
+ */
+export declare function FreeschemaQueryApi(query: FreeschemaQuery, token?: string): Promise<any>;

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

@@ -0,0 +1,68 @@
+/**
+ * Search API module for querying concepts across compositions.
+ * This module provides the primary search functionality for the Concept Connection System,
+ * enabling users to search for concepts by type, name, and composition with pagination support.
+ *
+ * @module Api/Search/Search
+ * @see https://documentation.freeschema.com for search query patterns and best practices
+ */
+/**
+ * Searches for concepts across specified compositions with pagination.
+ * This is the primary search function for retrieving concepts based on type,
+ * search text, and composition. It performs a GET request with URL-encoded
+ * parameters to find matching concepts in the CCS database.
+ *
+ * @param type - The concept type to search for (e.g., "Person", "Organization", "Document")
+ * @param search - The search text to match against concept names or properties
+ * @param composition - The composition ID or name to search within
+ * @param token - Authentication token for authorized access
+ * @param inpage - Number of results per page (defaults to 10)
+ * @param page - Page number for pagination, starting from 1 (defaults to 1)
+ * @returns Promise resolving to an array of matching concepts, or empty array on error
+ *
+ * @example
+ * ```typescript
+ * // Search for Person concepts in a specific composition
+ * const results = await SearchAllConcepts(
+ *   "Person",
+ *   "John",
+ *   "my-composition-123",
+ *   "auth-token-456",
+ *   20,  // 20 results per page
+ *   1    // first page
+ * );
+ * console.log(`Found ${results.length} matching persons`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Search with default pagination
+ * const results = await SearchAllConcepts(
+ *   "Document",
+ *   "report",
+ *   "documents-composition",
+ *   authToken
+ * );
+ * // Returns first 10 results by default
+ * ```
+ *
+ * @remarks
+ * This function uses URL-encoded parameters for the GET request, which is ideal for
+ * simple search operations. For more complex queries, consider using FreeschemaQueryApi.
+ *
+ * Error handling:
+ * - HTTP errors are handled via HandleHttpError and logged
+ * - Network errors are caught, logged, and re-thrown
+ * - Returns empty array on HTTP errors, throws exception on network errors
+ *
+ * Pagination:
+ * - Results are paginated server-side
+ * - Use 'inpage' to control page size
+ * - Use 'page' to navigate through results
+ * - Page numbers start at 1, not 0
+ *
+ * @see FreeschemaQueryApi for complex queries
+ * @see SearchInternalApi for searching within internal compositions
+ * @see SearchWithLinker for linked concept searches
+ */
+export declare function SearchAllConcepts(type: string, search: string, composition: string, token: string, inpage?: number, page?: number): Promise<any>;

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

@@ -0,0 +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

@@ -0,0 +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

@@ -0,0 +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

@@ -0,0 +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>;