import { ComKey, PriKey } from '@fjell/types';
/**
 * Configuration for PathBuilder
 */
export interface PathBuilderConfig {
    bucketName: string;
    directoryPaths: string[];
    basePath?: string;
    useJsonExtension?: boolean;
    keySharding?: {
        enabled?: boolean;
        levels?: number;
        charsPerLevel?: number;
    };
}
/**
 * Utility class for building GCS paths from Fjell keys
 */
export declare class PathBuilder {
    private readonly bucketName;
    private readonly directoryPaths;
    private readonly basePath;
    private readonly useJsonExtension;
    private readonly shardingEnabled;
    private readonly shardingLevels;
    private readonly charsPerLevel;
    constructor(config: PathBuilderConfig);
    /**
     * Build full GCS path from a key
     */
    buildPath(key: PriKey<any> | ComKey<any, any, any, any, any, any>): string;
    /**
     * Build path for a primary key
     */
    private buildPriKeyPath;
    /**
     * Build path for a composite key
     */
    private buildComKeyPath;
    /**
     * Build sharded path for primary key
     */
    buildShardedPath(directory: string, filename: string): string;
    /**
     * Build shard directory parts from a primary key
     * Example: 'abc123' with levels=2, charsPerLevel=1 → ['a', 'ab']
     */
    private buildShardParts;
    /**
     * Get directory path for a key type
     */
    private getDirectoryForKeyType;
    /**
     * Build directory path (without filename)
     */
    buildDirectory(kt: string, index: number): string;
    /**
     * Build filename from primary key
     */
    private buildFilename;
    /**
     * Strip .json extension if present
     */
    private stripExtension;
    /**
     * Join path parts, handling empty strings and duplicate slashes
     */
    private joinPaths;
    /**
     * Parse a GCS path back to a key (best effort)
     * Returns null if the path doesn't match expected patterns
     */
    parsePathToKey(path: string): PriKey<any> | ComKey<any, any, any, any, any, any> | null;
    /**
     * Get the bucket name
     */
    getBucketName(): string;
    /**
     * Get the base path
     */
    getBasePath(): string;
    /**
     * Build directory path from locations for listing operations
     */
    buildDirectoryFromLocations(locations: any[]): string;
    /**
     * Build path to the files directory for an item
     * Example: user/23-34-32/recording/2443-332/_files
     */
    buildFilesDirectory(key: PriKey<any> | ComKey<any, any, any, any, any, any>, filesDir?: string): string;
    /**
     * Build path to a specific file
     * Example: user/23-34-32/recording/2443-332/_files/master/0.wav
     */
    buildFilePath(key: PriKey<any> | ComKey<any, any, any, any, any, any>, label: string, filename: string, filesDir?: string): string;
    /**
     * Build path to a label directory
     * Example: user/23-34-32/recording/2443-332/_files/master
     */
    buildLabelDirectory(key: PriKey<any> | ComKey<any, any, any, any, any, any>, label: string, filesDir?: string): string;
    /**
     * Parse file path to extract key, label, and filename
     * Example: user/23-34-32/recording/2443-332/_files/master/0.wav
     * Returns: { key: ComKey, label: 'master', filename: '0.wav' }
     */
    parseFilePath(path: string, filesDir?: string): {
        key: PriKey<any> | ComKey<any, any, any, any, any, any>;
        label: string;
        filename: string;
    } | null;
}