import { Problem } from './problem';
import { ProblemProvider } from './provider';
import { ProblemQueryOptions } from './query';
/**
 * Repository for accessing problems from registered providers.
 *
 * The repository is the primary interface for consumers to interact with
 * problems. It provides a unified API for querying, counting, and retrieving
 * problems from registered {@link ProblemProvider}s.
 *
 * Packages register their providers with the repository during initialization.
 * Consumers then use the repository's query methods rather than interacting
 * with providers directly.
 *
 * @example Registering a provider
 * ```ts
 * import {
 *     Action,
 *     PlatformServiceName,
 *     Problem,
 *     ProblemProvider,
 *     ProblemStatus,
 *     ProblemType,
 * } from '@limetech/lime-web-components';
 *
 * class EmailProblemProvider implements ProblemProvider {
 *     public id = 'email-integration';
 *     public title = 'Email Integration';
 *     public description = 'Problems related to email sending and delivery';
 *     public icon = 'envelope';
 *
 *     public async getProblems(): Promise<Omit<Problem, 'providerId'>[]> {
 *         return [];
 *     }
 *
 *     public async getCount(): Promise<number> {
 *         return 0;
 *     }
 *
 *     public async get(): Promise<Omit<Problem, 'providerId'> | undefined> {
 *         return undefined;
 *     }
 *
 *     public getActions(): Action[] {
 *         return [];
 *     }
 *
 *     public getTypes(): ProblemType[] {
 *         return [{ id: 'delivery-failed', title: 'Delivery Failed' }];
 *     }
 *
 *     public getType(type: string): ProblemType | undefined {
 *         return this.getTypes().find((candidate) => candidate.id === type);
 *     }
 *
 *     public getStatuses(): ProblemStatus[] {
 *         return [{ id: 'open', title: 'Open' }];
 *     }
 *
 *     public getStatus(status: string): ProblemStatus | undefined {
 *         return this.getStatuses().find((candidate) => candidate.id === status);
 *     }
 * }
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * repository.registerProvider(new EmailProblemProvider());
 * ```
 *
 * @example Getting actions for a problem
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * const problem = await repository.get('email-integration', 'prob-123');
 *
 * if (problem) {
 *     const provider = repository.getProvider(problem.providerId);
 *     const actions = provider?.getActions(problem) ?? [];
 * }
 * ```
 *
 * @see {@link ProblemProvider} for the provider interface
 *
 * @alpha
 * @group Problem
 */
export interface ProblemRepository {
    /**
     * Registers a problem provider with the repository.
     *
     * The provider's {@link ProblemProvider.id} must be unique. Registering
     * a provider with an id that already exists will throw an error.
     *
     * @param provider - The provider to register. Must have a unique id.
     * @throws Error if a provider with the same id is already registered.
     */
    registerProvider(provider: ProblemProvider): void;
    /**
     * Returns all registered providers.
     *
     * Useful for displaying provider information in the UI, such as
     * provider titles and icons for filtering.
     *
     * @returns An array of all registered providers.
     */
    getProviders(): ProblemProvider[];
    /**
     * Returns a specific provider by its id.
     *
     * @param id - The unique identifier of the provider.
     * @returns The provider if found, undefined otherwise.
     */
    getProvider(id: string): ProblemProvider | undefined;
    /**
     * Fetches problems from a provider matching the query options.
     *
     * @param providerId - The provider id to query.
     * @param options - Optional filtering and pagination options.
     * @returns A promise resolving to an array of problems.
     * @throws Error if no provider with the given id is registered.
     *
     * @example Fetching every problem, then only the critical ones
     * ```ts
     * import {
     *     PlatformServiceName,
     *     ProblemSeverity,
     * } from '@limetech/lime-web-components';
     *
     * const repository = platform.get(PlatformServiceName.ProblemRepository);
     *
     * const emailProblems = await repository.getProblems('email-integration');
     *
     * const criticalProblems = await repository.getProblems('email-integration', {
     *     severity: ProblemSeverity.Critical,
     * });
     * ```
     */
    getProblems(providerId: string, options?: ProblemQueryOptions): Promise<Problem[]>;
    /**
     * Returns the count of problems from a provider.
     *
     * More efficient than fetching all problems when only the count is needed.
     *
     * @param providerId - The provider id to query.
     * @param options - Optional filtering options.
     * @returns A promise resolving to the count.
     * @throws Error if no provider with the given id is registered.
     */
    getCount(providerId: string, options?: ProblemQueryOptions): Promise<number>;
    /**
     * Retrieves a specific problem by provider and problem id.
     *
     * @param providerId - The id of the provider that owns the problem.
     * @param problemId - The id of the problem within that provider.
     * @returns A promise resolving to the problem if found, undefined otherwise.
     * @throws Error if no provider with the given id is registered.
     */
    get(providerId: string, problemId: string): Promise<Problem | undefined>;
}