import {
	InsiderAppCardsCampaignResponse,
	InsiderAppCard,
	InsiderAppCardButton,
} from './InsiderAppCard';

/**
 * Main API for accessing and managing app cards (campaigns) functionality.
 *
 * This interface provides methods to retrieve app card campaigns and notifications
 * from the Insider platform. App cards can contain text, images, and
 * interactive buttons.
 *
 * The app cards API allows you to:
 * - Fetch app card campaigns with their content and metadata
 * - Access app card read/unread status
 * - Handle interactive buttons within app cards
 * - Support multiple content types (text, images)
 */
interface InsiderAppCards {
	/**
	 * Retrieves the user's app card campaigns.
	 *
	 * Fetches all available app cards from the Insider platform for the current user.
	 * This method cancels any pending campaign requests before initiating a new one.
	 *
	 * The campaign response contains app cards that may include:
	 * - Marketing notifications and promotional content
	 * - Multi-media content (text, images)
	 * - Interactive buttons with associated actions
	 * - Read/unread status for each app card
	 *
	 * @param completion - A completion handler called when the campaigns are retrieved or an error occurs.
	 * The completion handler takes two parameters:
	 * - error: An error object if the request fails, undefined otherwise.
	 * - campaignResponse: An InsiderAppCardsCampaignResponse containing the user's app cards. Will be undefined if an error occurred.
	 *
	 * @example
	 * ```typescript
	 * appCards.getCampaigns((error, campaignResponse) => {
	 *   if (error) {
	 *     console.log('Failed to fetch campaigns:', error.message);
	 *   } else {
	 *     campaignResponse.appCards.forEach(appCard => {
	 *       console.log('App Card Id:', appCard.id, 'Read:', appCard.isRead);
	 *     });
	 *   }
	 * });
	 * ```
	 */
	getCampaigns(completion: (error?: Error, campaignResponse?: InsiderAppCardsCampaignResponse) => void): void;

	/**
	 * Retrieves the user's app card campaigns and returns a promise.
	 *
	 * Fetches all available app cards from the Insider platform for the current user.
	 * This method cancels any pending campaign requests before initiating a new one.
	 *
	 * @returns A Promise that resolves with the campaign response or rejects with an error.
	 *
	 * @example
	 * ```typescript
	 * try {
	 *   const campaignResponse = await appCards.getCampaigns();
	 *   campaignResponse.appCards.forEach(appCard => {
	 *     console.log('App Card Id:', appCard.id, 'Read:', appCard.isRead);
	 *   });
	 * } catch (error) {
	 *   console.log('Failed to fetch campaigns:', error.message);
	 * }
	 * ```
	 */
	getCampaigns(): Promise<InsiderAppCardsCampaignResponse>;

	/**
	 * Marks specified app cards as read.
	 *
	 * Updates the read status of one or more app cards to indicate they have been viewed by the user.
	 * This operation synchronizes with the Insider backend to persist the read state across devices.
	 *
	 * @param appCardIds - An array of app card identifiers to mark as read. Each Id should correspond to a valid
	 * app card Id from the campaigns. Empty arrays are allowed but will result in no operation.
	 * @param completion - A completion handler called when the operation finishes.
	 * The completion handler takes one parameter:
	 * - error: An error object if the request fails, undefined if successful.
	 *
	 * @example
	 * ```typescript
	 * appCards.markAsRead(['card_123', 'card_456'], (error) => {
	 *   if (error) {
	 *     console.log('Failed to mark app cards as read:', error.message);
	 *   } else {
	 *     console.log('App cards marked as read successfully');
	 *   }
	 * });
	 * ```
	 *
	 * @remarks App card Ids that don't exist are silently ignored.
	 */
	markAsRead(appCardIds: string[], completion: (error?: Error) => void): void;

	/**
	 * Marks specified app cards as read and returns a promise.
	 *
	 * Updates the read status of one or more app cards to indicate they have been viewed by the user.
	 * This operation synchronizes with the Insider backend to persist the read state across devices.
	 *
	 * @param appCardIds - An array of app card identifiers to mark as read. Each Id should correspond to a valid
	 * app card Id from the campaigns. Empty arrays are allowed but will result in no operation.
	 * @returns A Promise that resolves when successful or rejects with an error.
	 *
	 * @example
	 * ```typescript
	 * try {
	 *   await appCards.markAsRead(['card_123', 'card_456']);
	 *   console.log('App cards marked as read successfully');
	 * } catch (error) {
	 *   console.log('Failed to mark app cards as read:', error.message);
	 * }
	 * ```
	 *
	 * @remarks App card Ids that don't exist are silently ignored.
	 */
	markAsRead(appCardIds: string[]): Promise<void>;

	/**
	 * Marks specified app cards as unread.
	 *
	 * Updates the read status of one or more app cards to indicate they are unread.
	 * This operation synchronizes with the Insider backend to persist the unread state across devices.
	 *
	 * @param appCardIds - An array of app card identifiers to mark as unread. Each Id should correspond to a valid
	 * app card Id from the campaigns. Empty arrays are allowed but will result in no operation.
	 * @param completion - A completion handler called when the operation finishes.
	 * The completion handler takes one parameter:
	 * - error: An error object if the request fails, undefined if successful.
	 *
	 * @example
	 * ```typescript
	 * appCards.markAsUnread(['card_123', 'card_456'], (error) => {
	 *   if (error) {
	 *     console.log('Failed to mark app cards as unread:', error.message);
	 *   } else {
	 *     console.log('App cards marked as unread successfully');
	 *   }
	 * });
	 * ```
	 *
	 * @remarks App card Ids that don't exist are silently ignored.
	 */
	markAsUnread(appCardIds: string[], completion: (error?: Error) => void): void;

	/**
	 * Marks specified app cards as unread and returns a promise.
	 *
	 * Updates the read status of one or more app cards to indicate they are unread.
	 * This operation synchronizes with the Insider backend to persist the unread state across devices.
	 *
	 * @param appCardIds - An array of app card identifiers to mark as unread. Each Id should correspond to a valid
	 * app card Id from the campaigns. Empty arrays are allowed but will result in no operation.
	 * @returns A Promise that resolves when successful or rejects with an error.
	 *
	 * @example
	 * ```typescript
	 * try {
	 *   await appCards.markAsUnread(['card_123', 'card_456']);
	 *   console.log('App cards marked as unread successfully');
	 * } catch (error) {
	 *   console.log('Failed to mark app cards as unread:', error.message);
	 * }
	 * ```
	 *
	 * @remarks App card Ids that don't exist are silently ignored.
	 */
	markAsUnread(appCardIds: string[]): Promise<void>;

	/**
	 * Deletes specified app cards.
	 *
	 * Permanently removes one or more app cards from the user's campaigns.
	 * This operation synchronizes with the Insider backend.
	 *
	 * @param appCardIds - An array of app card identifiers to delete.
	 * @param completion - A completion handler called when the operation finishes.
	 *
	 * @example
	 * ```typescript
	 * appCards.delete(['card_123', 'card_456'], (error) => {
	 *   if (error) {
	 *     console.log('Failed to delete app cards:', error.message);
	 *   } else {
	 *     console.log('App cards deleted successfully');
	 *   }
	 * });
	 * ```
	 */
	delete(appCardIds: string[], completion: (error?: Error) => void): void;

	/**
	 * Deletes specified app cards and returns a promise.
	 *
	 * Permanently removes one or more app cards from the user's campaigns.
	 * This operation synchronizes with the Insider backend.
	 *
	 * @param appCardIds - An array of app card identifiers to delete.
	 * @returns A Promise that resolves when successful or rejects with an error.
	 *
	 * @example
	 * ```typescript
	 * try {
	 *   await appCards.delete(['card_123', 'card_456']);
	 *   console.log('App cards deleted successfully');
	 * } catch (error) {
	 *   console.log('Failed to delete app cards:', error.message);
	 * }
	 * ```
	 */
	delete(appCardIds: string[]): Promise<void>;

	/**
	 * Records a view event for an app card.
	 *
	 * Call this method when a user views an app card.
	 * This notifies observers and can be used for analytics tracking.
	 *
	 * @param appCard - The app card that was viewed.
	 *
	 * @example
	 * ```typescript
	 * appCards.view(appCard);
	 * ```
	 */
	view(appCard: InsiderAppCard): void;

	/**
	 * Records a click event for an app card.
	 *
	 * Call this method when a user clicks or taps on an app card.
	 * This executes the app card's deeplink action (if present) and notifies observers.
	 *
	 * @param appCard - The app card that was clicked.
	 *
	 * @example
	 * ```typescript
	 * appCards.click(appCard);
	 * ```
	 */
	click(appCard: InsiderAppCard): void;

	/**
	 * Records a click event for a button within an app card.
	 *
	 * Call this method when a user clicks or taps on a button in an app card.
	 * This executes the button's action (if present) and notifies observers.
	 *
	 * @param button - The button that was clicked.
	 *
	 * @example
	 * ```typescript
	 * appCards.clickButton(button);
	 * ```
	 */
	clickButton(button: InsiderAppCardButton): void;
}

declare const InsiderAppCards: InsiderAppCards;

export default InsiderAppCards;