/**
 * Reusable HTTP storage services for FileTree-style backends.
 * @packageDocumentation
 */

import { Converter } from '@fgv/ts-utils';
import { Hono } from 'hono';
import type { Logging } from '@fgv/ts-utils';
import { Result } from '@fgv/ts-utils';

/**
 * Builds storage routes for a Hono app.
 * @public
 */
export declare function createStorageRoutes(options: ICreateStorageRoutesOptions): Hono;

/**
 * Filesystem-backed implementation of {@link IHttpStorageProvider}.
 * @public
 */
export declare class FsStorageProvider implements IHttpStorageProvider {
    private readonly _rootPath;
    constructor(rootPath: string);
    getItem(itemPath: string): Promise<Result<IStorageTreeItem>>;
    getChildren(itemPath: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
    getFile(itemPath: string): Promise<Result<IStorageFileResponse>>;
    saveFile(itemPath: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
    deleteFile(itemPath: string): Promise<Result<boolean>>;
    createDirectory(itemPath: string): Promise<Result<IStorageTreeItem>>;
    sync(): Promise<Result<IStorageSyncResponse>>;
    private _resolveAbsolutePath;
    private _toTreeItem;
}

/**
 * Namespace-aware provider factory backed by filesystem directories.
 * @public
 */
export declare class FsStorageProviderFactory implements IHttpStorageProviderFactory {
    private readonly _rootPath;
    constructor(options: IFsStorageProviderFactoryOptions);
    forNamespace(namespace?: string): Result<IHttpStorageProvider>;
}

/**
 * Service layer for storage API operations.
 * @public
 */
export declare class HttpStorageService {
    private readonly _providers;
    constructor(providers: IHttpStorageProviderFactory);
    getItem(request: IStoragePathRequest): Promise<Result<IStorageTreeItem>>;
    getChildren(request: IStoragePathRequest): Promise<Result<IStorageTreeChildrenResponse>>;
    getFile(request: IStoragePathRequest): Promise<Result<IStorageFileResponse>>;
    saveFile(request: IStorageWriteFileRequest): Promise<Result<IStorageFileResponse>>;
    deleteFile(request: IStoragePathRequest): Promise<Result<boolean>>;
    createDirectory(request: IStoragePathRequest): Promise<Result<IStorageTreeItem>>;
    sync(request: IStorageSyncRequest): Promise<Result<IStorageSyncResponse>>;
    private _getProvider;
}

/**
 * Options for creating storage routes.
 * @public
 */
export declare interface ICreateStorageRoutesOptions {
    readonly providers: IHttpStorageProviderFactory;
    readonly logger?: Logging.ILogger;
}

/**
 * Options for creating filesystem-backed storage providers.
 * @public
 */
export declare interface IFsStorageProviderFactoryOptions {
    readonly rootPath: string;
}

/**
 * Provider contract for storage backends.
 * All methods are async to support both filesystem and database backends.
 * @public
 */
export declare interface IHttpStorageProvider {
    getItem(path: string): Promise<Result<IStorageTreeItem>>;
    getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
    getFile(path: string): Promise<Result<IStorageFileResponse>>;
    saveFile(path: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
    deleteFile(path: string): Promise<Result<boolean>>;
    createDirectory(path: string): Promise<Result<IStorageTreeItem>>;
    sync(): Promise<Result<IStorageSyncResponse>>;
}

/**
 * Factory for creating namespace-scoped storage providers.
 * @public
 */
export declare interface IHttpStorageProviderFactory {
    forNamespace(namespace?: StorageNamespace): Result<IHttpStorageProvider>;
}

/**
 * Response for reading a file.
 * @public
 */
export declare interface IStorageFileResponse {
    readonly path: string;
    readonly contents: string;
    readonly contentType?: string;
}

/**
 * Request for path-based operations.
 * @public
 */
export declare interface IStoragePathRequest {
    readonly path: string;
    readonly namespace?: StorageNamespace;
}

/**
 * Request for sync operation.
 * @public
 */
export declare interface IStorageSyncRequest {
    readonly namespace?: StorageNamespace;
}

/**
 * Sync response metadata.
 * @public
 */
export declare interface IStorageSyncResponse {
    readonly synced: number;
}

/**
 * Response for listing children.
 * @public
 */
export declare interface IStorageTreeChildrenResponse {
    readonly path: string;
    readonly children: ReadonlyArray<IStorageTreeItem>;
}

/**
 * Storage tree item metadata.
 * @public
 */
export declare interface IStorageTreeItem {
    readonly path: string;
    readonly name: string;
    readonly type: StorageItemType;
}

/**
 * Request for writing file contents.
 * @public
 */
export declare interface IStorageWriteFileRequest extends IStoragePathRequest {
    readonly contents: string;
    readonly contentType?: string;
}

/**
 * Normalizes a request path to a consistent POSIX format.
 * @public
 */
export declare function normalizeRequestPath(requestPath: string): string;

/**
 * Sanitize namespace path segment.
 * @public
 */
export declare function sanitizeNamespace(namespace?: string): Result<string>;

/**
 * Converter for file responses.
 * @public
 */
export declare const storageFileResponse: Converter<IStorageFileResponse>;

/**
 * Storage item type.
 * @public
 */
export declare type StorageItemType = 'file' | 'directory';

/**
 * Namespace identifier for scoped storage.
 * @public
 */
export declare type StorageNamespace = string;

/**
 * Converter for path-based requests.
 * @public
 */
export declare const storagePathRequest: Converter<IStoragePathRequest>;

/**
 * Converter for sync requests.
 * @public
 */
export declare const storageSyncRequest: Converter<IStorageSyncRequest>;

/**
 * Converter for children list responses.
 * @public
 */
export declare const storageTreeChildrenResponse: Converter<IStorageTreeChildrenResponse>;

/**
 * Converter for {@link IStorageTreeItem}.
 * @public
 */
export declare const storageTreeItem: Converter<IStorageTreeItem>;

/**
 * Converter for write-file requests.
 * @public
 */
export declare const storageWriteFileRequest: Converter<IStorageWriteFileRequest>;

export { }