import { Acl } from './acl';
import { LimeProperty } from './property';
/**
 * Represents a Lime type definition in the Lime CRM system.
 *
 * A {@link LimeType} defines the schema and metadata for a business object type (e.g., company, person, deal).
 * It contains information about properties, access control, labels, and provides methods to
 * navigate the type structure including related types through property relations.
 *
 * {@link LimeType | LimeTypes} are the foundation of the type system and describe:
 * - What properties an object of this type has (see {@link LimeProperty})
 * - How those properties relate to other types
 * - Access control rules ({@link Acl}) for the type
 * - Localized names, and a `label` marking special-purpose types
 *
 * @example Accessing limetype properties
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.LimeTypeRepository);
 * const dealType = repository.getLimeType('deal');
 *
 * if (dealType) {
 *     console.log('Display name:', dealType.localname.singular);
 *     console.log('Properties:', Object.keys(dealType.properties));
 *     console.log('Can update:', dealType.acl.update);
 * }
 * ```
 *
 * @public
 * @group Lime types
 */
export interface LimeType {
    /**
     * Internal name of the limetype (e.g., 'company', 'person', 'deal').
     * This is the identifier used in API calls and code.
     */
    name: string;
    /**
     * Label marking this limetype for a specific system usage, e.g. `company`,
     * `person`, or `deal`.
     *
     * A limetype's `name` can be anything a schema defines, so `label` is how
     * the system recognizes a type's special-purpose role independent of its
     * name. There are many more labels than the common examples, defined by
     * Lime CRM or by the installation's configuration; most limetypes have
     * none.
     *
     * Use `localname.singular` or `localname.plural` for user-facing text.
     */
    label: string;
    /**
     * Access control list defining permissions for this type.
     * Determines what operations (read, write, delete, etc.) are allowed.
     * See {@link Acl} for details on permission structure.
     */
    acl: Acl;
    /**
     * Localized names for the limetype.
     * Contains both singular and plural forms based on current user language.
     */
    localname: {
        /** Singular form (e.g., 'Company', 'Person') */
        singular: string;
        /** Plural form (e.g., 'Companies', 'People') */
        plural: string;
    };
    /**
     * Map of all properties defined on this limetype.
     * Key is the property name, value is the {@link LimeProperty} definition.
     *
     * @example Reading the property map
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const repository = platform.get(PlatformServiceName.LimeTypeRepository);
     * const limetype = repository.getLimeType('person');
     *
     * const nameProperty = limetype?.properties['name'];
     * const allPropertyNames = Object.keys(limetype?.properties ?? {});
     * ```
     */
    properties: Record<string, LimeProperty>;
    /**
     * Get a property by name, with support for navigating relations using dot notation.
     *
     * This method allows you to retrieve property definitions, including properties
     * on related objects. When you specify a path like 'company.phone', it will:
     * 1. Get the 'company' property from this limetype
     * 2. Follow the relation to the company limetype
     * 3. Return the 'phone' property from the company limetype
     *
     * @param name - Name of property to get. Can use dot notation to traverse
     * relations (e.g., 'company.phone' to get phone property of related company)
     *
     * @throws Will throw an error containing the name of the missing property
     * if the property does not exist
     *
     * @returns The property definition for the specified property
     *
     * @example Getting a property, directly and across a relation
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const repository = platform.get(PlatformServiceName.LimeTypeRepository);
     * const dealType = repository.getLimeType('deal');
     *
     * if (dealType) {
     *     const nameProperty = dealType.getProperty('name');
     *     console.log(nameProperty.type); // 'string'
     *
     *     // Dot notation follows the relation to the company type
     *     const phoneProperty = dealType.getProperty('company.phone');
     *     console.log(phoneProperty.type); // 'phone'
     *     console.log(phoneProperty.localname); // 'Phone'
     *
     *     const contactNameProperty = dealType.getProperty('contact.name');
     *     if (contactNameProperty.required) {
     *         console.log('Contact name is required');
     *     }
     * }
     * ```
     */
    getProperty(name: string): LimeProperty;
}