import { Icon } from '../core';
import { ProblemSeverity } from './problem';
/**
 * Filter for querying problems related to {@link LimeObject}s.
 *
 * Used with {@link ProblemQueryOptions.context} to find problems linked to
 * specific limeobjects. The limetype is always required, while id is optional:
 * - With only `limetype`: Returns all problems related to that object type
 * - With both `limetype` and `id`: Returns problems for that specific object
 *
 * @example Find all problems related to contacts
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * const contactProblems = await repository.getProblems('email-integration', {
 *     context: { limetype: 'contact' },
 * });
 * ```
 *
 * @example Find problems for a specific deal
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * const dealProblems = await repository.getProblems('external-crm-sync', {
 *     context: {
 *         limetype: 'deal',
 *         id: 98_765,
 *     },
 * });
 * ```
 *
 * @see {@link ProblemQueryOptions.context}
 * @see {@link ProblemContext} for the context stored on problems
 *
 * @alpha
 * @group Problem
 */
export type ProblemContextFilter = {
    /**
     * The limetype to filter by (e.g., 'contact', 'deal', 'company').
     *
     * This is required because object ids are only unique within a limetype.
     */
    limetype: string;
    /**
     * The specific object id to filter by.
     *
     * When omitted, matches all problems related to the specified limetype.
     */
    id?: number;
};
/**
 * Options for querying problems from a {@link ProblemProvider}.
 *
 * All filter properties are optional. Providers handle what they support and
 * silently ignore unsupported filters. This allows the platform to pass a
 * consistent set of filters without needing to know each provider's capabilities.
 *
 * Multiple values can be provided for most filters (severity, status, type, tags)
 * to match problems that have any of the specified values (OR logic).
 *
 * @example Get all open problems
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * const openProblems = await repository.getProblems('email-integration', {
 *     status: 'open',
 * });
 * ```
 *
 * @example Get high-priority unresolved problems with pagination
 * ```ts
 * import {
 *     PlatformServiceName,
 *     ProblemSeverity,
 * } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * const urgentProblems = await repository.getProblems('email-integration', {
 *     severity: [ProblemSeverity.High, ProblemSeverity.Critical],
 *     status: ['open', 'acknowledged'],
 *     limit: 20,
 *     offset: 0,
 * });
 * ```
 *
 * @example Get problems for a specific type and user
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * const userEmailProblems = await repository.getProblems('email-integration', {
 *     type: 'email.delivery-failed',
 *     userId: 'user-123',
 * });
 * ```
 *
 * @example Get problems related to a specific limeobject
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * const dealProblems = await repository.getProblems('external-crm-sync', {
 *     context: {
 *         limetype: 'deal',
 *         id: 98_765,
 *     },
 * });
 * ```
 *
 * @see {@link ProblemProvider.getProblems}
 * @see {@link ProblemProvider.getCount}
 *
 * @alpha
 * @group Problem
 */
export interface ProblemQueryOptions {
    /**
     * Filter by severity level(s).
     *
     * When a single value is provided, returns problems with that severity.
     * When an array is provided, returns problems matching any of the severities.
     *
     * @see {@link ProblemSeverity}
     */
    severity?: ProblemSeverity | ProblemSeverity[];
    /**
     * Filter by status(es).
     *
     * Status values are provider-defined strings. When a single value is provided,
     * returns problems with that status. When an array is provided, returns
     * problems matching any of the statuses.
     *
     * @see {@link Problem.status}
     */
    status?: string | string[];
    /**
     * Filter by problem type(s).
     *
     * Types are provider-specific strings like 'email.delivery-failed' or
     * 'sync.connection-error'. When an array is provided, returns problems
     * matching any of the types.
     *
     * @see {@link Problem."type"}
     */
    type?: string | string[];
    /**
     * Filter by tag(s).
     *
     * Returns problems that have any of the specified tags (OR logic).
     *
     * @see {@link Problem.tags}
     */
    tags?: string[];
    /**
     * Filter by user identifier.
     *
     * Returns problems associated with the specified user.
     *
     * @see {@link Problem.userId}
     */
    userId?: string;
    /**
     * Filter by related {@link LimeObject}.
     *
     * Use this to find problems linked to a specific limetype or object instance.
     *
     * @see {@link ProblemContextFilter}
     * @see {@link Problem.context}
     */
    context?: ProblemContextFilter;
    /**
     * Maximum number of problems to return.
     *
     * Used for pagination. When omitted, the provider decides the default limit.
     */
    limit?: number;
    /**
     * Number of problems to skip before returning results.
     *
     * Used for pagination in combination with `limit`. For example, to get
     * the second page of 20 items, use `{ limit: 20, offset: 20 }`.
     */
    offset?: number;
}
/**
 * Display information for a problem type.
 *
 * Providers define multiple problem types (e.g., an Email Integration provider
 * might have 'delivery-failed', 'validation-error', 'attachment-too-large').
 * ProblemType provides the human-readable display information for each type.
 *
 * The platform retrieves this information via {@link ProblemProvider.getType}
 * and {@link ProblemProvider.getTypes} to display problems with appropriate
 * titles and icons.
 *
 * @example Implementing type methods in a provider
 * ```ts
 * import { ProblemProvider, ProblemType } from '@limetech/lime-web-components';
 *
 * class EmailProblemTypes
 *     implements Pick<ProblemProvider, 'getTypes' | 'getType'>
 * {
 *     private types: ProblemType[] = [
 *         {
 *             id: 'delivery-failed',
 *             title: 'Delivery Failed',
 *             description: 'Email could not be delivered to the recipient',
 *             icon: 'envelope-exclamation',
 *         },
 *         {
 *             id: 'validation-error',
 *             title: 'Validation Error',
 *         },
 *     ];
 *
 *     public getTypes(): ProblemType[] {
 *         return this.types;
 *     }
 *
 *     public getType(type: string): ProblemType | undefined {
 *         return this.types.find((candidate) => candidate.id === type);
 *     }
 * }
 * ```
 *
 * @see {@link ProblemProvider.getType}
 * @see {@link ProblemProvider.getTypes}
 * @see {@link Problem."type"}
 *
 * @alpha
 * @group Problem
 */
export interface ProblemType {
    /**
     * The type identifier as used in {@link Problem."type"}.
     */
    id: string;
    /**
     * Human-readable title for the problem type.
     *
     * Displayed as the primary label for problems of this type. Should be
     * concise but descriptive (e.g., 'Delivery Failed', 'Connection Error').
     */
    title: string;
    /**
     * Detailed description of what this type of problem means.
     *
     * Provides context to help users understand the nature of the problem.
     * May be displayed in tooltips or detail views.
     */
    description?: string;
    /**
     * Icon to display for problems of this type.
     *
     * Can be either a string referencing an icon name from the platform's icon
     * library, or an {@link Icon} object with additional properties like color.
     *
     * @see {@link Icon}
     */
    icon?: string | Icon;
}
/**
 * Display information for a problem status.
 *
 * Since status values are provider-defined, providers must supply display
 * information for their statuses so the platform can render them appropriately.
 *
 * @example Implementing the status methods in a provider
 * ```ts
 * import { ProblemProvider, ProblemStatus } from '@limetech/lime-web-components';
 *
 * class EmailProblemStatuses
 *     implements Pick<ProblemProvider, 'getStatus' | 'getStatuses'>
 * {
 *     private statusInfoMap: Record<string, ProblemStatus> = {
 *         open: {
 *             id: 'open',
 *             title: 'Open',
 *             icon: 'circle',
 *         },
 *         'pending-retry': {
 *             id: 'pending-retry',
 *             title: 'Pending Retry',
 *             icon: 'clock',
 *         },
 *         resolved: {
 *             id: 'resolved',
 *             title: 'Resolved',
 *             icon: 'check-circle',
 *         },
 *     };
 *
 *     public getStatus(status: string): ProblemStatus | undefined {
 *         return this.statusInfoMap[status];
 *     }
 *
 *     public getStatuses(): ProblemStatus[] {
 *         return Object.values(this.statusInfoMap);
 *     }
 * }
 * ```
 *
 * @see {@link ProblemProvider.getStatus}
 * @see {@link ProblemProvider.getStatuses}
 * @see {@link Problem.status}
 *
 * @alpha
 * @group Problem
 */
export interface ProblemStatus {
    /**
     * The status identifier as used in {@link Problem.status}.
     */
    id: string;
    /**
     * Human-readable title for the status.
     */
    title: string;
    /**
     * Icon to display for this status.
     *
     * Can be either a string referencing an icon name from the platform's icon
     * library, or an {@link Icon} object with additional properties like color.
     *
     * @see {@link Icon}
     */
    icon?: string | Icon;
}