@limetech/lime-web-components 6.4.0 → 6.5.0

package/dist/conditionregistry/conditionregistry.d.ts

@@ -1,30 +1,160 @@
 import { Action } from '../action';
 import { LimeObject } from '../limeobject';
 /**
- * This interface defines callbacks intended to be registered to the {@link Condition} registry
+ * Represents a conditional evaluation rule that can be registered and used
+ * throughout the application.
+ *
+ * Conditions are predicate functions that determine whether certain UI elements should be
+ * visible, enabled, or available based on runtime state. For example, they can be used to:
+ * - Control action visibility (show/hide menu items based on object state)
+ * - Enable/disable features based on user permissions or context
+ * - Filter lists of items based on dynamic criteria
+ * - Implement business rules for conditional UI rendering
+ *
+ * Each condition has a unique ID and a type that indicates what kind of subject it evaluates.
+ * The most common types are 'limeobject' and 'action', but custom types can be defined.
+ *
+ * @example
+ * Registering a simple LimeObject condition
+ * ```typescript
+ * const registry = platform.get(PlatformServiceName.ConditionRegistry);
+ *
+ * const isDealWon = {
+ *     id: 'deal.is-won',
+ *     type: 'limeobject',
+ *     evaluate: (deal) => deal.dealstatus === 'won'
+ * };
+ *
+ * registry.addCondition(isDealWon);
+ * ```
+ *
+ * @example
+ * Condition with additional parameters
+ * ```typescript
+ * const hasMinimumValue = {
+ *     id: 'object.min-value',
+ *     type: 'limeobject',
+ *     evaluate: (object, params) => {
+ *         const { field, minValue } = params;
+ *         const value = object[field];
+ *         return typeof value === 'number' && value >= minValue;
+ *     }
+ * };
+ *
+ * const isHighValue = hasMinimumValue.evaluate(dealObject, {
+ *     field: 'value',
+ *     minValue: 100000
+ * });
+ * ```
+ *
+ * @see {@link ConditionRegistry} for managing conditions
+ * @see {@link LimeObjectCondition} for LimeObject-specific conditions
+ * @see {@link ActionCondition} for action-specific conditions
  *
  * @beta
  * @group Conditions
  */
 export type Condition<T = unknown> = {
     /**
-     * The condition type, describing what to evaluate the condition for, for example "limeobject"
+     * The type of subject this condition evaluates.
+     *
+     * Common types include:
+     * - `limeobject` - Evaluates {@link LimeObject} instances
+     * - `action` - Evaluates {@link Action} instances
+     *
+     * Custom types can be defined for specialized evaluation contexts.
      */
     type: string;
     /**
-     * The evaluation function relating to this condition, serves the role of a predicate
+     * The evaluation function that determines if the condition is met.
+     *
+     * This predicate function receives the subject to evaluate and optional parameters
+     * for configuration. It should return `true` if the condition is satisfied,
+     * `false` otherwise.
+     *
+     * The function should be pure and side-effect free when possible, as it may be
+     * called frequently during UI rendering and updates.
+     *
+     * @param subject - The value to evaluate. Type depends on the condition type.
+     * For 'limeobject' conditions, this is a {@link LimeObject}.
+     * For 'action' conditions, this is an {@link Action}.
+     * @param params - Optional configuration data for the evaluation.
+     * Can be used to pass context-specific values like field names, thresholds,
+     * or other criteria. The evaluation function should validate params if used.
+     * @returns `true` if the condition is met, `false` otherwise.
+     * @throws May throw an error if params has an unexpected type or required data is missing.
+     *
+     * @example
+     * Simple boolean check
+     * ```typescript
+     * const evaluate = (deal: LimeObject) => deal.dealstatus === 'won';
+     * ```
      *
-     * @param subject - some value depending on the condition type to evaluate the condition for,
-     * such as the current limeobject
-     * @param params - any additional data that this condition may expect, such as configuration
-     * data from an action visibility condition
-     * @throws may throw an error if the second argument has an unexpected type
+     * @example
+     * Using params for configuration
+     * ```typescript
+     * const evaluate = (obj: LimeObject, params?: { propertyName: string }) => {
+     *     return obj.getValue(params.propertyName) !== null;
+     * };
+     * ```
      */
     evaluate: (subject: T, params?: unknown) => boolean;
+    /**
+     * Unique identifier for this condition.
+     *
+     * The ID is used to reference the condition when registering, removing, or
+     * looking it up from the {@link ConditionRegistry}. It must be unique across
+     * all registered conditions.
+     */
     id: string;
 };
 /**
- * A condition to evaluate for a {@link LimeObject}
+ * A specialized condition type for evaluating {@link LimeObject} instances.
+ *
+ * LimeObject conditions are the most common type of condition, used to control
+ * UI elements based on the state of business objects (deals, contacts, companies, etc.).
+ * The evaluate function receives a LimeObject and can check any of its properties
+ * to determine if the condition is met.
+ *
+ * @example
+ * Condition based on object status
+ * ```typescript
+ * const registry = platform.get(PlatformServiceName.ConditionRegistry);
+ *
+ * const isDealActive = {
+ *     id: 'deal.is-active',
+ *     type: 'limeobject',
+ *     evaluate: (deal) => {
+ *         return deal.dealstatus === 'qualification' ||
+ *                deal.dealstatus === 'proposal';
+ *     }
+ * };
+ *
+ * registry.addCondition(isDealActive);
+ *
+ * const condition = registry.getCondition('deal.is-active');
+ * const isActive = condition.evaluate(deal);
+ * ```
+ *
+ * @example
+ * Condition for conditional action visibility
+ * ```typescript
+ * const canSendEmail = {
+ *     id: 'contact.can-send-email',
+ *     type: 'limeobject',
+ *     evaluate: (contact) => contact.email && contact.email.length > 0
+ * };
+ *
+ * const sendEmailAction = {
+ *     label: 'Send Email',
+ *     icon: 'envelope',
+ *     command: { name: 'send-email' },
+ *     condition: canSendEmail
+ * };
+ * ```
+ *
+ * @see {@link Condition} for the base condition type
+ * @see {@link LimeObject} for the object structure
  *
  * @beta
  * @group Conditions
@@ -33,7 +163,29 @@ export type LimeObjectCondition = Condition<LimeObject> & {
     type: 'limeobject';
 };
 /**
- * A condition to evaluate for an {@link Action}
+ * A specialized condition type for evaluating {@link Action} instances.
+ *
+ * Action conditions are used to control the availability or visibility of actions
+ * themselves, based on properties of the action. This is less common than {@link LimeObject}
+ * conditions but useful for creating dynamic action menus that filter or organize
+ * actions based on their metadata.
+ *
+ * @example
+ * Condition to filter bulk actions
+ * ```typescript
+ * const registry = platform.get(PlatformServiceName.ConditionRegistry);
+ *
+ * const isBulkAction = {
+ *     id: 'action.is-bulk',
+ *     type: 'action',
+ *     evaluate: (action) => action.command.name.startsWith('bulk-')
+ * };
+ *
+ * registry.addCondition(isBulkAction);
+ * ```
+ *
+ * @see {@link Condition} for the base condition type
+ * @see {@link Action} for the action structure
  *
  * @beta
  * @group Conditions
@@ -42,7 +194,7 @@ export type ActionCondition = Condition<Action> & {
     type: 'action';
 };
 /**
- * Check if condition expects a lime object to be passed when it is evaluated
+ * Check if condition expects a {@link LimeObject} to be passed when it is evaluated
  *
  * @param condition - the condition to check
  * @returns true if the condition is a condition for a {@link LimeObject},
@@ -64,45 +216,176 @@ export declare function isLimeObjectCondition(condition: Condition): condition i
  */
 export declare function isActionCondition(condition: Condition): condition is Condition<Action>;
 /**
- * Service for adding and retrieving, and checking {@link Condition}s to and from the condition registry
+ * Central registry for managing conditional evaluation rules across the application.
+ *
+ * The ConditionRegistry acts as a global repository for {@link Condition} instances,
+ * allowing different parts of the application to register, retrieve, and evaluate
+ * conditions. This is particularly useful for:
+ * - Controlling action visibility based on object state
+ * - Implementing permission-based UI rendering
+ * - Creating dynamic, context-aware interfaces
+ * - Sharing reusable business logic across components
+ *
+ * Components typically access the registry via the platform service and register
+ * their conditions when the application initializes. Conditions can be
+ * added and removed dynamically, allowing for flexible runtime configuration.
+ *
+ * @example
+ * Registering and using conditions in a component
+ * ```typescript
+ * const registry = platform.get(PlatformServiceName.ConditionRegistry);
+ *
+ * const canWinDeal = {
+ *     id: 'deal.can-win',
+ *     type: 'limeobject',
+ *     evaluate: (deal) => deal.dealstatus === 'proposal' && deal.value > 0
+ * };
+ *
+ * const canLoseDeal = {
+ *     id: 'deal.can-lose',
+ *     type: 'limeobject',
+ *     evaluate: (deal) => deal.dealstatus !== 'lost' && deal.dealstatus !== 'won'
+ * };
+ *
+ * registry.addCondition(canWinDeal);
+ * registry.addCondition(canLoseDeal);
+ *
+ * const actions = [
+ *     {
+ *         label: 'Mark as Won',
+ *         icon: 'trophy',
+ *         command: { name: 'win-deal' },
+ *         condition: registry.getCondition('deal.can-win')
+ *     },
+ *     {
+ *         label: 'Mark as Lost',
+ *         icon: 'times',
+ *         command: { name: 'lose-deal' },
+ *         condition: registry.getCondition('deal.can-lose')
+ *     }
+ * ];
+ *
+ * const availableActions = actions.filter(action => {
+ *     return !action.condition || action.condition.evaluate(deal);
+ * });
+ * ```
+ *
+ * @see {@link Condition} for the condition structure
+ * @see {@link LimeObjectCondition} for object-specific conditions
+ * @see {@link ActionCondition} for action-specific conditions
  *
  * @beta
  * @group Conditions
  */
 export interface ConditionRegistry {
     /**
-     * Add a {@link Condition} to the registry
+     * Registers a new condition in the registry.
+     *
+     * The condition's ID must be unique across all registered conditions.
+     * If a condition with the same ID already exists, this method throws an error.
+     * It's recommended to register conditions during application startup.
      *
-     * @param condition - the condition to pass to the registry
-     * @throws error if the id already exists in the registry
+     * @param condition - The condition to register. Must have a unique ID.
+     * @throws Error if a condition with the same ID already exists in the registry.
+     *
+     * @example
+     * ```typescript
+     * const isActive: LimeObjectCondition = {
+     *     id: 'deal.is-active',
+     *     type: 'limeobject',
+     *     evaluate: (deal) => deal.dealstatus === 'active'
+     * };
+     *
+     * registry.addCondition(isActive);
+     * ```
      */
     addCondition(condition: Condition): any;
     /**
-     * Remove a {@link Condition} from the registry
+     * Removes a condition from the registry.
+     *
+     * The condition is identified by its ID. If no condition with the given ID
+     * exists in the registry, this method throws an error.
+     *
+     * @param condition - The condition to remove. Must exist in the registry.
+     * @throws Error if the condition's ID does not exist in the registry.
      *
-     * @param condition - the condition to remove
-     * @throws error if the id does not exist in the registry
+     * @example
+     * ```typescript
+     * const condition = registry.getCondition('deal.is-active');
+     * registry.removeCondition(condition);
+     * ```
+     *
+     * @example
+     * Safe removal with existence check
+     * ```typescript
+     * if (registry.hasCondition('deal.is-active')) {
+     *     registry.removeCondition(registry.getCondition('deal.is-active'));
+     * }
+     * ```
      */
     removeCondition(condition: Condition): any;
     /**
-     * Checks if a {@link Condition} exists on the registry
+     * Checks whether a condition with the given ID exists in the registry.
+     *
+     * This method is useful for defensive programming, allowing you to verify
+     * that a condition exists before attempting to retrieve or remove it.
+     *
+     * @param id - The unique identifier of the condition to check.
+     * @returns `true` if a condition with the ID exists, `false` otherwise.
      *
-     * @param id - id of the condition
-     * @returns true if it exists, false otherwise
+     * @example
+     * ```typescript
+     * if (registry.hasCondition('deal.can-win')) {
+     *     const condition = registry.getCondition('deal.can-win');
+     *     const canWin = condition.evaluate(deal);
+     * }
+     * ```
      */
     hasCondition(id: string): boolean;
     /**
-     * Gets all {@link Condition}s
+     * Retrieves all registered conditions.
      *
-     * @returns a list of all existing conditions
+     * This method returns a list of all conditions currently in the registry,
+     * regardless of their type. This can be useful for debugging, inspection,
+     * or building dynamic UIs that need to enumerate available conditions.
+     *
+     * @returns An array of all registered conditions.
+     *
+     * @example
+     * ```typescript
+     * const allConditions = registry.getConditions();
+     * console.log(`Found ${allConditions.length} conditions`);
+     *
+     * const limeObjectConditions = allConditions.filter(
+     *     c => c.type === 'limeobject'
+     * );
+     * ```
      */
     getConditions(): Condition[];
     /**
-     * Gets a {@link Condition} by id
+     * Retrieves a specific condition by its unique identifier.
+     *
+     * If no condition with the given ID exists, this method throws an error.
+     * Use {@link ConditionRegistry.hasCondition} first if you need to check for existence.
+     *
+     * @param id - The unique identifier of the condition to retrieve.
+     * @returns The condition with the specified ID.
+     * @throws Error if no condition with the given ID exists in the registry.
+     *
+     * @example
+     * ```typescript
+     * const canWin = registry.getCondition('deal.can-win');
+     * const isEligible = canWin.evaluate(dealObject);
+     * ```
      *
-     * @param id - id of the condition
-     * @throws error if no condition was found with the specified id
-     * @returns the condition with the specified id
+     * @example
+     * Safe retrieval with type checking
+     * ```typescript
+     * const condition = registry.getCondition('deal.is-active');
+     * if (isLimeObjectCondition(condition)) {
+     *     const result = condition.evaluate(myDeal);
+     * }
+     * ```
      */
     getCondition(id: string): Condition;
 }

package/dist/conditionregistry/conditionregistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conditionregistry.d.ts","sourceRoot":"","sources":["../../src/conditionregistry/conditionregistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,IAAI;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;OAQG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IAKpD,EAAE,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG;IACtD,IAAI,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG;IAC9C,IAAI,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACjC,SAAS,EAAE,SAAS,GACrB,SAAS,IAAI,SAAS,CAAC,UAAU,CAAC,CAEpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC7B,SAAS,EAAE,SAAS,GACrB,SAAS,IAAI,SAAS,CAAC,MAAM,CAAC,CAEhC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,OAAE;IAEnC;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,SAAS,OAAE;IAEtC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC;;;;OAIG;IACH,aAAa,IAAI,SAAS,EAAE,CAAC;IAE7B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC"}
+{"version":3,"file":"conditionregistry.d.ts","sourceRoot":"","sources":["../../src/conditionregistry/conditionregistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,IAAI;IACjC;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IAEpD;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG;IACtD,IAAI,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG;IAC9C,IAAI,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACjC,SAAS,EAAE,SAAS,GACrB,SAAS,IAAI,SAAS,CAAC,UAAU,CAAC,CAEpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC7B,SAAS,EAAE,SAAS,GACrB,SAAS,IAAI,SAAS,CAAC,MAAM,CAAC,CAEhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,OAAE;IAEnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CAAC,SAAS,EAAE,SAAS,OAAE;IAEtC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,IAAI,SAAS,EAAE,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC"}

package/dist/config/decorator.d.ts

@@ -8,10 +8,57 @@ export interface SelectConfigOptions extends StateOptions {
     name?: string;
 }
 /**
- * Gets an object with all configs where key is used as key.
+ * Decorator that subscribes to configuration data from the {@link ConfigRepository}.
+ *
+ * This decorator automatically updates the decorated property whenever configuration
+ * data changes in the platform. Returns an object with all configs where the config
+ * key is used as the key. It's the recommended approach over manual subscriptions as
+ * it handles subscription lifecycle automatically.
+ *
+ * @param options - Configuration including key filtering and state transformation via {@link SelectConfigOptions}
+ * @returns A PropertyDecorator that sets up automatic subscription to config data
+ *
+ * @remarks
+ * Subscribes to: {@link ConfigRepository}
+ *
+ * Updates: The decorated property with configuration data (object or specific value)
+ *
+ * Lifecycle: Automatically subscribes in `connectedCallback` and unsubscribes
+ * in `disconnectedCallback`
+ *
+ * @example
+ * Get all configuration data
+ * ```typescript
+ * @State()
+ * @SelectConfig({})
+ * private config: Record<string, unknown>;
+ *
+ * render() {
+ *     return (
+ *         <div>
+ *             <h2>Configuration</h2>
+ *             <pre>{JSON.stringify(this.config, null, 2)}</pre>
+ *         </div>
+ *     );
+ * }
+ * ```
+ *
+ * @example
+ * Get specific config value by name
+ * ```typescript
+ * @State()
+ * @SelectConfig({
+ *     name: 'apiEndpoint',
+ *     map: [(config) => config?.url || 'https://api.example.com']
+ * })
+ * private apiUrl: string;
+ *
+ * async fetchData() {
+ *     const response = await fetch(`${this.apiUrl}/data`);
+ *     return response.json();
+ * }
+ * ```
  *
- * @param options - state decorator options
- * @returns state decorator
  * @public
  * @group Config
  */

package/dist/config/decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../src/config/decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,YAAY,EAEf,MAAM,SAAS,CAAC;AAGjB;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAM5E"}
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../src/config/decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,YAAY,EAEf,MAAM,SAAS,CAAC;AAGjB;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAM5E"}

package/dist/config/repository.d.ts

@@ -1,29 +1,150 @@
 import { StateRepository } from '../core/state';
 /**
+ * Repository for storing and retrieving application-wide configuration data.
+ *
+ * {@link ConfigRepository} provides persistent key-value storage for configuration
+ * that applies to all users across the application. Typical use cases include:
+ * - View configurations (card layouts, table columns, form structures)
+ * - Plugin-specific configuration settings
+ *
+ * Each plugin or package typically manages its own configuration namespace,
+ * storing settings that define how components should be rendered or behave
+ * for all users.
+ *
+ * **Important:** This repository is NOT for user preferences. User-specific
+ * settings should use {@link UserPreferencesRepository} instead.
+ *
+ * Configuration data is:
+ * - Stored persistently in the database
+ * - Shared across all users and sessions
+ * - Read-only for non-admin users (set method requires admin privileges)
+ *
+ * The repository extends {@link StateRepository}, providing reactive state
+ * management with automatic UI updates when configuration changes.
+ *
+ * Access the repository through the platform service:
+ * ```typescript
+ * const repo = this.platform.get(PlatformServiceName.ConfigRepository);
+ * ```
+ *
+ * @example
+ * Read view configuration
+ * ```typescript
+ * const repo = platform.get(PlatformServiceName.ConfigRepository);
+ *
+ * if (repo.has('webclient_view.company')) {
+ *     const cardConfig = repo.get('webclient_view.company').card;
+ *     renderCard(cardConfig);
+ * }
+ * ```
+ *
+ * @example
+ * Read plugin configuration with type safety
+ * ```typescript
+ * const repo = platform.get(PlatformServiceName.ConfigRepository);
+ *
+ * if (!repo.has('my_plugin_config')) {
+ *     return useDefaultConfig();
+ * }
+ *
+ * const pluginConfig = repo.get('my_plugin_config');
+ * const isEnabled = pluginConfig?.enabled ?? false;
+ * ```
+ *
  * @public
  * @group Config
+ * @see {@link StateRepository} for subscription patterns
  */
 export interface ConfigRepository extends StateRepository {
     /**
-     * Check if a config exists
+     * Check if a configuration key exists.
      *
-     * @param key - name of the key containing the config
-     * @returns true if config exists
+     * Returns `true` if configuration data has been stored under the specified key,
+     * `false` otherwise. Use this to check for the existence of optional configuration
+     * before attempting to retrieve it.
+     *
+     * @param key - Name of the configuration key to check
+     * @returns `true` if the configuration exists, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * // Check before loading view config
+     * const repo = platform.get(PlatformServiceName.ConfigRepository);
+     *
+     * if (repo.has('person_table_columns')) {
+     *     const columns = repo.get('person_table_columns');
+     *     renderTable(columns);
+     * } else {
+     *     // Use default columns
+     *     renderTable(defaultColumns);
+     * }
+     * ```
+     *
+     * @see {@link ConfigRepository.get} to retrieve configuration values
+     * @see {@link ConfigRepository.set} to store configuration values
      */
     has(key: string): boolean;
     /**
-     * Get config from the state
+     * Get configuration data for a key.
+     *
+     * Retrieves the configuration value stored under the specified key.
+     * Returns the stored data, or `undefined` if the key doesn't exist.
+     *
+     * Use the type parameter `<T>` to specify the expected type of the configuration
+     * data for type safety. The repository does not validate types at runtime.
+     *
+     * @param key - Name of the configuration key to retrieve
+     * @returns The stored configuration data, or `undefined` if not found
+     * @throws May throw if the stored data cannot be deserialized
+     *
+     * @example
+     * ```typescript
+     * // Get view configuration
+     * const repo = platform.get(PlatformServiceName.ConfigRepository);
+     * const cardConfig = repo.get('webclient_view.company').card;
+     * ```
      *
-     * @param key - name of the key containing the config
-     * @returns the config
+     * @see {@link ConfigRepository.has} to check if a key exists
+     * @see {@link ConfigRepository.set} to store configuration values
      */
     get<T = any>(key: string): T;
     /**
-     * Set config
+     * Save configuration data under a key.
+     *
+     * > **Important:** This method requires admin privileges. The backend endpoint
+     * > is protected and will reject requests from non-admin users.
+     *
+     * Stores the provided data persistently under the specified key. If the key
+     * already exists, its value is overwritten. The data is serialized and saved
+     * to the database, making it available to all users across the application.
+     *
+     * After saving, the repository state is updated, triggering any subscriptions.
+     * The data can be any serializable JavaScript value (objects, arrays, primitives).
+     *
+     * @param key - Name of the configuration key to set
+     * @param data - Configuration data to store (must be serializable)
+     * @returns Promise that resolves when the data is saved
+     * @throws Error if save fails, data cannot be serialized, or user lacks admin privileges
+     *
+     * @example
+     * ```typescript
+     * // Admin: Set plugin configuration
+     * const repo = platform.get(PlatformServiceName.ConfigRepository);
+     *
+     * const pluginConfig: PluginConfiguration = {
+     *     enabled: true,
+     *     apiEndpoint: 'https://api.example.com',
+     *     settings: {
+     *         timeout: 5000,
+     *         retries: 3
+     *     }
+     * };
+     *
+     * await repo.set('my_plugin_config', pluginConfig);
+     * ```
      *
-     * @param key - name of the key containing the config
-     * @param data - the config data
-     * @returns a promise that will be resolved when the config has been saved
+     * @see {@link ConfigRepository.get} to retrieve stored configuration
+     * @see {@link ConfigRepository.has} to check if a key exists
      */
     set<T = any>(key: string, data: T): Promise<void>;
 }

package/dist/config/repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/config/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACrD;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE1B;;;;;OAKG;IAEH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;IAE7B;;;;;;OAMG;IAEH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/config/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACrD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE1B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IAEH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IAEH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD"}