import type { B2CInstance } from '../../instance/index.js';
import type { WaitForJobOptions } from '../jobs/run.js';
/** The special site ID for Business Manager. */
export declare const BM_SITE_ID = "Sites-Site";
/** Position options for adding a cartridge. */
export type CartridgePosition = 'first' | 'last' | 'before' | 'after';
/** Options for adding a cartridge to a site's cartridge path. */
export interface AddCartridgeOptions {
    /** Cartridge name to add. */
    name: string;
    /** Position to add the cartridge (default: 'first'). */
    position: CartridgePosition;
    /** Target cartridge name (required when position is 'before' or 'after'). */
    target?: string;
}
/** Options for cartridge path update operations that may run jobs. */
export interface CartridgeUpdateOptions {
    /** Callback for operation-level status messages (e.g. "Exporting site preferences..."). */
    log?: (message: string) => void;
    /** Wait options for underlying job execution (polling interval, timeout, progress). */
    waitOptions?: WaitForJobOptions;
}
/** Result of a cartridge path operation. */
export interface CartridgePathResult {
    /** Site ID. */
    siteId: string;
    /** Colon-separated cartridge path string. */
    cartridges: string;
    /** Cartridge names as an ordered array. */
    cartridgeList: string[];
}
/**
 * Gets the cartridge path for a site.
 *
 * Uses OCAPI `GET /sites/{site_id}` to read the cartridge path.
 * Works for all sites including Business Manager (Sites-Site).
 *
 * @param instance - B2C instance to query
 * @param siteId - Site ID (e.g. 'RefArch', 'Sites-Site')
 * @returns Cartridge path result
 *
 * @example
 * ```typescript
 * const result = await getCartridgePath(instance, 'RefArch');
 * console.log(result.cartridgeList); // ['app_storefront_base', 'plugin_applepay']
 *
 * // Business Manager
 * const bmResult = await getCartridgePath(instance, 'Sites-Site');
 * ```
 */
export declare function getCartridgePath(instance: B2CInstance, siteId: string): Promise<CartridgePathResult>;
/**
 * Adds a cartridge to a site's cartridge path.
 *
 * For regular sites, tries OCAPI `POST /sites/{site_id}/cartridges` first,
 * falling back to site archive import if OCAPI permissions are unavailable.
 * For Business Manager (Sites-Site), always uses site archive import.
 *
 * @param instance - B2C instance
 * @param siteId - Site ID
 * @param options - Cartridge name, position, and optional target
 * @returns Updated cartridge path
 *
 * @example
 * ```typescript
 * // Add to beginning (default)
 * await addCartridge(instance, 'RefArch', { name: 'my_cartridge', position: 'first' });
 *
 * // Add before a specific cartridge
 * await addCartridge(instance, 'RefArch', {
 *   name: 'my_cartridge', position: 'before', target: 'app_storefront_base'
 * });
 *
 * // Business Manager
 * await addCartridge(instance, 'Sites-Site', { name: 'bm_ext', position: 'first' });
 * ```
 */
export declare function addCartridge(instance: B2CInstance, siteId: string, options: AddCartridgeOptions, updateOptions?: CartridgeUpdateOptions): Promise<CartridgePathResult>;
/**
 * Removes a cartridge from a site's cartridge path.
 *
 * For regular sites, tries OCAPI `DELETE /sites/{site_id}/cartridges/{cartridge_name}`
 * first, falling back to site archive import if OCAPI permissions are unavailable.
 * For Business Manager (Sites-Site), always uses site archive import.
 *
 * @param instance - B2C instance
 * @param siteId - Site ID
 * @param cartridgeName - Name of the cartridge to remove
 * @returns Updated cartridge path
 *
 * @example
 * ```typescript
 * await removeCartridge(instance, 'RefArch', 'old_cartridge');
 * ```
 */
export declare function removeCartridge(instance: B2CInstance, siteId: string, cartridgeName: string, updateOptions?: CartridgeUpdateOptions): Promise<CartridgePathResult>;
/**
 * Replaces the entire cartridge path for a site.
 *
 * For regular sites, tries OCAPI `PUT /sites/{site_id}/cartridges` first,
 * falling back to site archive import if OCAPI permissions are unavailable.
 * For Business Manager (Sites-Site), always uses site archive import.
 *
 * @param instance - B2C instance
 * @param siteId - Site ID
 * @param cartridges - New cartridge path (colon-separated string)
 * @returns Updated cartridge path
 *
 * @example
 * ```typescript
 * await setCartridgePath(instance, 'RefArch', 'app_storefront_base:plugin_applepay');
 * ```
 */
export declare function setCartridgePath(instance: B2CInstance, siteId: string, cartridges: string, updateOptions?: CartridgeUpdateOptions): Promise<CartridgePathResult>;