/**
 * Available severity levels for problems.
 *
 * Severity indicates the urgency and impact of a problem, helping users
 * prioritize which issues need attention first. The levels are:
 * - `Low` - Minor issues that don't significantly impact operations
 * - `Medium` - Issues that should be addressed but aren't urgent
 * - `High` - Important issues requiring prompt attention
 * - `Critical` - Severe issues that need immediate action
 *
 * @example Setting severity when creating a problem
 * ```ts
 * import { Problem, ProblemSeverity } from '@limetech/lime-web-components';
 *
 * const problem: Problem = {
 *     id: 'email-123',
 *     providerId: 'email-integration',
 *     type: 'delivery-failed',
 *     description: 'Email could not be delivered to recipient',
 *     createdAt: new Date().toISOString(),
 *     severity: ProblemSeverity.High,
 * };
 * ```
 *
 * @example Filtering problems by severity
 * ```ts
 * import {
 *     PlatformServiceName,
 *     ProblemSeverity,
 * } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.ProblemRepository);
 *
 * const criticalProblems = await repository.getProblems('email-integration', {
 *     severity: ProblemSeverity.Critical,
 * });
 *
 * const urgentProblems = await repository.getProblems('email-integration', {
 *     severity: [ProblemSeverity.High, ProblemSeverity.Critical],
 * });
 * ```
 *
 * @alpha
 * @group Problem
 */
export declare const ProblemSeverity: {
    readonly Low: "low";
    readonly Medium: "medium";
    readonly High: "high";
    readonly Critical: "critical";
};
/**
 * Severity level for a problem, indicating urgency and impact.
 *
 * @see {@link ProblemSeverity} for available values
 *
 * @alpha
 * @group Problem
 */
export type ProblemSeverity = (typeof ProblemSeverity)[keyof typeof ProblemSeverity];
/**
 * Links a problem to a specific {@link LimeObject}.
 *
 * When a problem is related to a specific business object (e.g., a contact
 * whose email bounced, or a deal that failed to sync), the context provides
 * the link to that object. This enables:
 * - Navigating from the problem to the related object
 * - Showing problems when viewing a specific object
 * - Filtering problems by related object type or instance
 *
 * @example Problem linked to a specific contact
 * ```ts
 * import { Problem } from '@limetech/lime-web-components';
 *
 * const problem: Problem = {
 *     id: 'email-789',
 *     providerId: 'email-integration',
 *     type: 'delivery-failed',
 *     description: 'Email bounced, invalid address',
 *     createdAt: new Date().toISOString(),
 *     context: {
 *         limetype: 'contact',
 *         id: 12_345,
 *     },
 * };
 * ```
 *
 * @see {@link Problem.context}
 * @see {@link ProblemContextFilter} for filtering by context
 *
 * @alpha
 * @group Problem
 */
export type ProblemContext = {
    /**
     * The limetype of the related object (e.g., 'contact', 'deal', 'company')
     */
    limetype: string;
    /**
     * The id of the specific object instance
     */
    id: number;
};
/**
 * Technical error details for a problem.
 *
 * While {@link Problem.description} provides a user-friendly explanation,
 * ProblemError captures the underlying technical details useful for debugging.
 * This separation allows the platform to show appropriate information to
 * different audiences.
 *
 * @example Problem with error details
 * ```ts
 * import { Problem, ProblemSeverity } from '@limetech/lime-web-components';
 *
 * const problem: Problem = {
 *     id: 'sync-error-042',
 *     providerId: 'external-crm-sync',
 *     type: 'connection-error',
 *     description: 'Failed to sync deal with external CRM',
 *     createdAt: '2024-01-15T14:22:00Z',
 *     severity: ProblemSeverity.High,
 *     status: 'pending-retry',
 *     context: { limetype: 'deal', id: 98_765 },
 *     error: {
 *         message: 'ETIMEDOUT: connection timed out after 30000ms',
 *         code: 'ETIMEDOUT',
 *         stack: 'Error: ETIMEDOUT\n    at TCPConnectWrap.afterConnect...',
 *     },
 * };
 * ```
 *
 * @see {@link Problem.error}
 *
 * @alpha
 * @group Problem
 */
export interface ProblemError {
    /**
     * Technical error message.
     *
     * This is the raw error message from the underlying system, which may
     * be more technical than the user-facing {@link Problem.description}.
     */
    message: string;
    /**
     * Error code for programmatic handling.
     *
     * Codes allow categorizing errors without parsing message text.
     * Use standard codes where applicable (e.g., `ETIMEDOUT`, `ECONNREFUSED`)
     * or provider-specific codes.
     */
    code?: string;
    /**
     * Stack trace for debugging.
     *
     * The full stack trace helps developers diagnose where errors originated.
     * May be displayed in an expandable "Technical Details" section.
     */
    stack?: string;
}
/**
 * Represents a problem reported by a {@link ProblemProvider}.
 *
 * Problems are system-level issues that require manual intervention, such as:
 * - Failed email delivery or validation errors
 * - Integration sync failures with external systems
 * - Background task configuration errors
 * - Data import issues with corrupt records
 *
 * Each problem belongs to a provider which owns the problem's lifecycle,
 * storage, and available actions. Problems can optionally be linked to a
 * specific {@link LimeObject} via the `context` property.
 *
 * The platform aggregates problems from all registered providers, allowing
 * authorized users to view and manage issues across the system.
 *
 * The generic type parameter `T` allows providers to define strongly-typed
 * metadata for their specific problem types.
 *
 * @typeParam T - The type of the metadata object. Defaults to `unknown`.
 *
 * @example Basic problem with required fields only
 * ```ts
 * import { Problem } from '@limetech/lime-web-components';
 *
 * const problem: Problem = {
 *     id: 'prob-001',
 *     providerId: 'email-integration',
 *     type: 'delivery-failed',
 *     description: 'Email to john@example.com bounced with error: mailbox full',
 *     createdAt: '2024-01-15T10:30:00Z',
 * };
 * ```
 *
 * @example Problem with error details
 * ```ts
 * import { Problem, ProblemSeverity } from '@limetech/lime-web-components';
 *
 * const problem: Problem = {
 *     id: 'sync-error-042',
 *     providerId: 'external-crm-sync',
 *     type: 'connection-error',
 *     description: 'Failed to sync deal with external CRM',
 *     createdAt: '2024-01-15T14:22:00Z',
 *     severity: ProblemSeverity.High,
 *     status: 'pending-retry',
 *     context: { limetype: 'deal', id: 98_765 },
 *     error: {
 *         message: 'ETIMEDOUT: connection timed out after 30000ms',
 *         code: 'ETIMEDOUT',
 *         stack: 'Error: ETIMEDOUT\n    at TCPConnectWrap.afterConnect...',
 *     },
 * };
 * ```
 *
 * @see {@link ProblemProvider} for the interface that supplies problems
 * @see {@link ProblemRepository} for registering providers and querying problems
 * @see {@link ProblemSeverity} for severity levels
 * @see {@link ProblemError} for technical error details
 *
 * @alpha
 * @group Problem
 */
export interface Problem<T = unknown> {
    /**
     * Unique identifier for the problem within the provider.
     *
     * The id only needs to be unique within a single provider. The combination
     * of `providerId` and `id` uniquely identifies a problem across the system.
     */
    id: string;
    /**
     * Identifier of the {@link ProblemProvider} that reported this problem.
     *
     * This links the problem back to its owning provider, which controls
     * the problem's lifecycle and available actions.
     *
     * This property is set automatically by the platform when problems are
     * returned from the {@link ProblemRepository}. Providers should not
     * include this property when returning problems from their methods.
     */
    providerId: string;
    /**
     * Type identifier for categorizing the problem.
     *
     * Types are provider-specific and allow grouping similar problems together.
     * Use a consistent naming convention, typically with a prefix indicating
     * the domain (e.g., 'email.delivery-failed', 'sync.connection-error').
     *
     * The provider's {@link ProblemProvider.getType} method returns display
     * information (title, description, icon) for each type.
     *
     * @example Prefixing the type with the provider's domain
     * ```ts
     * import { Problem } from '@limetech/lime-web-components';
     *
     * const emailProblem: Problem = {
     *     id: 'email-123',
     *     providerId: 'email-integration',
     *     type: 'email.delivery-failed',
     *     description: 'Email to john@example.com could not be delivered',
     *     createdAt: '2024-01-15T10:30:00Z',
     * };
     *
     * const syncProblem: Problem = {
     *     id: 'sync-042',
     *     providerId: 'external-crm-sync',
     *     type: 'sync.connection-error',
     *     description: 'Could not reach the external CRM',
     *     createdAt: '2024-01-15T14:22:00Z',
     * };
     * ```
     */
    type: string;
    /**
     * Human-readable description of what went wrong.
     *
     * The description should be clear enough for users to understand the issue
     * without needing technical knowledge. Include relevant details like
     * affected entities, error messages, or suggested actions.
     *
     * @example A clear description next to an overly technical one
     * ```ts
     * import { Problem } from '@limetech/lime-web-components';
     *
     * const clearProblem: Problem = {
     *     id: 'email-123',
     *     providerId: 'email-integration',
     *     type: 'email.delivery-failed',
     *     description:
     *         'Email to john@example.com could not be delivered: mailbox is full',
     *     createdAt: '2024-01-15T10:30:00Z',
     * };
     *
     * const tooTechnicalProblem: Problem = {
     *     id: 'email-124',
     *     providerId: 'email-integration',
     *     type: 'email.delivery-failed',
     *     // A user cannot act on an SMTP code alone. Say what failed and why.
     *     description: 'SMTP 452 4.2.2 error',
     *     createdAt: '2024-01-15T10:31:00Z',
     * };
     * ```
     */
    description: string;
    /**
     * ISO 8601 timestamp when the problem was first detected.
     *
     * @example Setting the timestamp from a stored value or from now
     * ```ts
     * import { Problem } from '@limetech/lime-web-components';
     *
     * const importedProblem: Problem = {
     *     id: 'email-123',
     *     providerId: 'email-integration',
     *     type: 'email.delivery-failed',
     *     description: 'Email could not be delivered',
     *     createdAt: '2024-01-15T10:30:00Z',
     * };
     *
     * const detectedNowProblem: Problem = {
     *     id: 'email-124',
     *     providerId: 'email-integration',
     *     type: 'email.delivery-failed',
     *     description: 'Email could not be delivered',
     *     createdAt: new Date().toISOString(),
     * };
     * ```
     */
    createdAt: string;
    /**
     * Severity level indicating the problem's urgency and impact.
     *
     * Use severity to help users prioritize which problems to address first.
     *
     * @see {@link ProblemSeverity}
     */
    severity?: ProblemSeverity;
    /**
     * Current status in the problem's lifecycle.
     *
     * Status is provider-defined. Each provider can define their own status
     * values that make sense for their workflow (e.g., 'open', 'in-progress',
     * 'pending-retry', 'resolved').
     *
     * Status is optional. Some providers may choose to simply remove problems
     * when they're resolved rather than tracking status transitions.
     */
    status?: string;
    /**
     * Tags for additional categorization and filtering.
     *
     * Tags provide flexible categorization beyond the `type` field. They can
     * represent things like affected systems, error categories, or custom
     * classifications specific to your domain.
     *
     * @example Tagging problems from three different providers
     * ```ts
     * import { Problem } from '@limetech/lime-web-components';
     *
     * const bouncedEmail: Problem = {
     *     id: 'email-123',
     *     providerId: 'email-integration',
     *     type: 'email.delivery-failed',
     *     description: 'Email bounced, the mailbox is full',
     *     createdAt: '2024-01-15T10:30:00Z',
     *     tags: ['email', 'bounce', 'permanent'],
     * };
     *
     * const syncTimeout: Problem = {
     *     id: 'sync-042',
     *     providerId: 'external-crm-sync',
     *     type: 'sync.connection-error',
     *     description: 'Could not reach the external CRM',
     *     createdAt: '2024-01-15T14:22:00Z',
     *     tags: ['sync', 'external-system', 'timeout'],
     * };
     *
     * const importFailure: Problem = {
     *     id: 'import-7',
     *     providerId: 'data-import',
     *     type: 'import.validation-error',
     *     description: 'Row 42 is missing a required field',
     *     createdAt: '2024-01-15T15:00:00Z',
     *     tags: ['import', 'validation', 'required-field'],
     * };
     * ```
     */
    tags?: string[];
    /**
     * Identifier of the user associated with this problem.
     *
     * This could be the user who triggered the action that failed, or the
     * user responsible for the affected data. The exact meaning depends on
     * the provider's context.
     */
    userId?: string;
    /**
     * Link to a related {@link LimeObject}.
     *
     * When a problem is directly related to a specific business object,
     * the context provides navigation and filtering capabilities.
     *
     * @see {@link ProblemContext}
     */
    context?: ProblemContext;
    /**
     * Technical error details for debugging.
     *
     * While `description` provides a user-friendly explanation, `error`
     * captures the underlying technical details. The platform may display
     * this in an expandable "Technical Details" section.
     *
     * @see {@link ProblemError}
     */
    error?: ProblemError;
    /**
     * Additional provider-specific data.
     *
     * Metadata allows providers to attach arbitrary data to problems that
     * may be useful for debugging, displaying additional details, or
     * powering actions. Values should be JSON-serializable.
     *
     * Use the generic type parameter to get type safety for your metadata.
     *
     * @example Typing the metadata with the generic parameter
     * ```ts
     * import { Problem } from '@limetech/lime-web-components';
     *
     * interface EmailProblemMetadata {
     *     originalEmailId: string;
     *     recipientEmail: string;
     *     bounceType: 'permanent' | 'temporary';
     *     smtpCode: number;
     * }
     *
     * const problem: Problem<EmailProblemMetadata> = {
     *     id: 'email-123',
     *     providerId: 'email-integration',
     *     type: 'delivery-failed',
     *     description: 'Email bounced',
     *     createdAt: '2024-01-15T10:30:00Z',
     *     metadata: {
     *         originalEmailId: 'msg-123',
     *         recipientEmail: 'john@example.com',
     *         bounceType: 'permanent',
     *         smtpCode: 550,
     *     },
     * };
     * ```
     */
    metadata?: T;
    /**
     * ISO 8601 timestamp when the problem was last modified.
     *
     * Updated when status changes, metadata is modified, or any other
     * property is updated after initial creation.
     */
    updatedAt?: string;
}