/**
 * CAR String Extension Utilities
 *
 * Provides parsing and manipulation functions for CAR strings with
 * extension suffixes. Extensions are declared in CAR strings using
 * the # suffix format.
 *
 * @packageDocumentation
 * @module @vorion/car-extensions/car-string-extensions
 * @license Apache-2.0
 *
 * @example
 * ```
 * // CAR string formats:
 * // Without extensions:
 * //   a3i.vorion.banquet-advisor:FHC-L3@1.2.0
 * //
 * // With single extension:
 * //   a3i.vorion.banquet-advisor:FHC-L3@1.2.0#gov
 * //
 * // With multiple extensions:
 * //   a3i.vorion.banquet-advisor:FHC-L3@1.2.0#gov,audit,hipaa
 * ```
 */
import { z } from 'zod';
/**
 * Result of parsing extensions from a CAR string
 */
export interface ParsedExtensions {
    /** The core CAR string (without extension suffix) */
    core: string;
    /** Array of extension shortcodes */
    extensions: string[];
}
/**
 * Zod schema for ParsedExtensions validation
 */
export declare const ParsedExtensionsSchema: z.ZodObject<{
    core: z.ZodString;
    extensions: z.ZodArray<z.ZodString, "many">;
}, "strip", z.ZodTypeAny, {
    extensions?: string[];
    core?: string;
}, {
    extensions?: string[];
    core?: string;
}>;
/**
 * Parse extension suffix from a CAR string
 *
 * Extracts the core CAR string and any extension shortcodes from
 * a CAR string that may include an extension suffix.
 *
 * @param car - The CAR string to parse (with or without extensions)
 * @returns Object containing core CAR string and array of extensions
 *
 * @example
 * ```typescript
 * // Without extensions
 * parseExtensions('a3i.vorion.agent:FHC-L3@1.0.0');
 * // { core: 'a3i.vorion.agent:FHC-L3@1.0.0', extensions: [] }
 *
 * // With single extension
 * parseExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov');
 * // { core: 'a3i.vorion.agent:FHC-L3@1.0.0', extensions: ['gov'] }
 *
 * // With multiple extensions
 * parseExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov,audit,hipaa');
 * // { core: 'a3i.vorion.agent:FHC-L3@1.0.0', extensions: ['gov', 'audit', 'hipaa'] }
 * ```
 */
export declare function parseExtensions(car: string): ParsedExtensions;
/**
 * Add an extension shortcode to a CAR string
 *
 * If the extension is already present, the string is returned unchanged.
 * Extensions are appended to the end of the extension list.
 *
 * @param car - The CAR string (with or without existing extensions)
 * @param extension - The extension shortcode to add
 * @returns The CAR string with the extension added
 *
 * @example
 * ```typescript
 * // Add to string without extensions
 * addExtension('a3i.vorion.agent:FHC-L3@1.0.0', 'gov');
 * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov'
 *
 * // Add to string with existing extensions
 * addExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'audit');
 * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov,audit'
 *
 * // Extension already present
 * addExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'gov');
 * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov'
 * ```
 */
export declare function addExtension(car: string, extension: string): string;
/**
 * Add multiple extensions to a CAR string
 *
 * Adds all specified extensions that are not already present.
 * Extensions are appended in the order provided.
 *
 * @param car - The CAR string (with or without existing extensions)
 * @param extensionsToAdd - Array of extension shortcodes to add
 * @returns The CAR string with all extensions added
 *
 * @example
 * ```typescript
 * addExtensions('a3i.vorion.agent:FHC-L3@1.0.0', ['gov', 'audit']);
 * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov,audit'
 * ```
 */
export declare function addExtensions(car: string, extensionsToAdd: string[]): string;
/**
 * Remove an extension shortcode from a CAR string
 *
 * If the extension is not present, the string is returned unchanged.
 * If removing the last extension, the # suffix is also removed.
 *
 * @param car - The CAR string with extensions
 * @param extension - The extension shortcode to remove
 * @returns The CAR string with the extension removed
 *
 * @example
 * ```typescript
 * // Remove from multiple extensions
 * removeExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov,audit', 'gov');
 * // 'a3i.vorion.agent:FHC-L3@1.0.0#audit'
 *
 * // Remove last extension
 * removeExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'gov');
 * // 'a3i.vorion.agent:FHC-L3@1.0.0'
 *
 * // Extension not present
 * removeExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'audit');
 * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov'
 * ```
 */
export declare function removeExtension(car: string, extension: string): string;
/**
 * Remove multiple extensions from a CAR string
 *
 * @param car - The CAR string with extensions
 * @param extensionsToRemove - Array of extension shortcodes to remove
 * @returns The CAR string with all specified extensions removed
 */
export declare function removeExtensions(car: string, extensionsToRemove: string[]): string;
/**
 * Check if a CAR string has a specific extension
 *
 * @param car - The CAR string to check
 * @param extension - The extension shortcode to look for
 * @returns True if the extension is present, false otherwise
 *
 * @example
 * ```typescript
 * hasExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov,audit', 'gov');
 * // true
 *
 * hasExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'audit');
 * // false
 *
 * hasExtension('a3i.vorion.agent:FHC-L3@1.0.0', 'gov');
 * // false
 * ```
 */
export declare function hasExtension(car: string, extension: string): boolean;
/**
 * Check if a CAR string has all specified extensions
 *
 * @param car - The CAR string to check
 * @param requiredExtensions - Array of extension shortcodes required
 * @returns True if all extensions are present, false otherwise
 */
export declare function hasAllExtensions(car: string, requiredExtensions: string[]): boolean;
/**
 * Check if a CAR string has any of the specified extensions
 *
 * @param car - The CAR string to check
 * @param extensionsToCheck - Array of extension shortcodes to check
 * @returns True if any extension is present, false otherwise
 */
export declare function hasAnyExtension(car: string, extensionsToCheck: string[]): boolean;
/**
 * Validate extension ID format
 *
 * Extension IDs must follow the format: car-ext-{name}-v{major}
 * Where {name} is lowercase letters and {major} is a positive integer.
 * Also accepts legacy car-ext-{name}-v{major} format for backwards compatibility.
 *
 * @param id - The extension ID to validate
 * @returns True if the ID is valid, false otherwise
 *
 * @example
 * ```typescript
 * isValidExtensionId('car-ext-governance-v1');  // true
 * isValidExtensionId('car-ext-healthcare-v2'); // true
 * isValidExtensionId('car-ext-governance-v1'); // true (backwards compatibility)
 * isValidExtensionId('car-ext-CAPS-v1');       // false (uppercase)
 * isValidExtensionId('my-extension');          // false (wrong format)
 * isValidExtensionId('car-ext-foo');           // false (missing version)
 * ```
 */
export declare function isValidExtensionId(id: string): boolean;
/**
 * Validate extension shortcode format
 *
 * Shortcodes must be 1-10 lowercase letters only.
 *
 * @param shortcode - The shortcode to validate
 * @returns True if the shortcode is valid, false otherwise
 *
 * @example
 * ```typescript
 * isValidShortcode('gov');     // true
 * isValidShortcode('hipaa');   // true
 * isValidShortcode('audit');   // true
 * isValidShortcode('GOV');     // false (uppercase)
 * isValidShortcode('gov1');    // false (contains number)
 * isValidShortcode('');        // false (empty)
 * isValidShortcode('verylongcode'); // false (too long)
 * ```
 */
export declare function isValidShortcode(shortcode: string): boolean;
/**
 * Validate a CAR string with optional extensions
 *
 * Validates that the CAR string follows the expected format including
 * any extension suffix.
 *
 * @param car - The CAR string to validate
 * @returns True if the CAR string is valid, false otherwise
 *
 * @example
 * ```typescript
 * isValidCARWithExtensions('a3i.vorion.agent:FHC-L3@1.0.0');           // true
 * isValidCARWithExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov');       // true
 * isValidCARWithExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov,audit'); // true
 * isValidCARWithExtensions('invalid-car-string');                      // false
 * ```
 */
export declare function isValidCARWithExtensions(car: string): boolean;
/**
 * @deprecated Use isValidCARWithExtensions instead
 */
export declare const isValidACIWithExtensions: typeof isValidCARWithExtensions;
/**
 * Get the extension count for a CAR string
 *
 * @param car - The CAR string to check
 * @returns Number of extensions in the CAR string
 */
export declare function getExtensionCount(car: string): number;
/**
 * Replace all extensions in a CAR string
 *
 * Removes any existing extensions and adds the new ones.
 *
 * @param car - The CAR string (with or without extensions)
 * @param newExtensions - Array of new extension shortcodes
 * @returns CAR string with only the new extensions
 *
 * @example
 * ```typescript
 * replaceExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov', ['audit', 'hipaa']);
 * // 'a3i.vorion.agent:FHC-L3@1.0.0#audit,hipaa'
 *
 * replaceExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov', []);
 * // 'a3i.vorion.agent:FHC-L3@1.0.0'
 * ```
 */
export declare function replaceExtensions(car: string, newExtensions: string[]): string;
/**
 * Sort extensions in a CAR string alphabetically
 *
 * @param car - The CAR string with extensions
 * @returns CAR string with extensions sorted alphabetically
 */
export declare function sortExtensions(car: string): string;
/**
 * Compare two CAR strings for extension equality
 *
 * Checks if two CAR strings have the same extensions (regardless of order).
 *
 * @param car1 - First CAR string
 * @param car2 - Second CAR string
 * @returns True if both have the same extensions
 */
export declare function haveEqualExtensions(car1: string, car2: string): boolean;
/**
 * Extract the core CAR string without extensions
 *
 * @param car - The CAR string (with or without extensions)
 * @returns The core CAR string
 */
export declare function getCoreCar(car: string): string;
/**
 * @deprecated Use getCoreCar instead
 */
export declare const getCoreCAR: typeof getCoreCar;
/**
 * @deprecated Use getCoreCar instead
 */
export declare const getCoreACI: typeof getCoreCar;
/**
 * Build a CAR string from core and extensions
 *
 * @param core - The core CAR string
 * @param extensions - Array of extension shortcodes
 * @returns Complete CAR string with extensions
 */
export declare function buildCAR(core: string, extensions: string[]): string;
/**
 * @deprecated Use buildCAR instead
 */
export declare const buildACI: typeof buildCAR;
/**
 * Parse extension ID to extract name and version
 *
 * @param extensionId - The extension ID (e.g., 'car-ext-governance-v1' or 'car-ext-governance-v1')
 * @returns Object with name and version, or null if invalid
 *
 * @example
 * ```typescript
 * parseExtensionId('car-ext-governance-v1');
 * // { name: 'governance', version: 1 }
 *
 * parseExtensionId('car-ext-governance-v1');
 * // { name: 'governance', version: 1 }
 *
 * parseExtensionId('invalid');
 * // null
 * ```
 */
export declare function parseExtensionId(extensionId: string): {
    name: string;
    version: number;
} | null;
/**
 * Build an extension ID from name and version
 *
 * @param name - Extension name (lowercase letters)
 * @param version - Major version number
 * @returns Extension ID in format car-ext-{name}-v{version}
 *
 * @example
 * ```typescript
 * buildExtensionId('governance', 1);
 * // 'car-ext-governance-v1'
 * ```
 */
export declare function buildExtensionId(name: string, version: number): string;
//# sourceMappingURL=car-string-extensions.d.ts.map