@warlock.js/core 4.0.161 → 4.0.163

package/esm/router/types.d.ts

@@ -0,0 +1,254 @@
+import type { GenericObject } from "@mongez/reinforcements";
+import type { ObjectValidator } from "@warlock.js/seal";
+import type { RouteShorthandOptions } from "fastify";
+import type { Request, Response, ReturnedResponse } from "../http";
+import type { ResponseSchema } from "../resource/types";
+/**
+ * Middleware response
+ */
+export type MiddlewareResponse = ReturnedResponse | undefined | void;
+/**
+ * Middleware method
+ * Receives the request and response objects
+ * And returns a response object or undefined if the request should continue
+ */
+export type Middleware<MiddlewareRequest extends Request = Request> = {
+    (request: MiddlewareRequest, response: Response): MiddlewareResponse;
+};
+export type RouterGroupCallback = () => void;
+export type RequestHandlerType = RequestHandler<any> | [GenericObject, string];
+/**
+ * Resource standard methods
+ */
+export type ResourceMethod = "list" | "get" | "create" | "update" | "delete" | "patch";
+export type RestfulMiddleware = Record<string, [Middleware]>;
+export type RequestHandlerValidation<TRequest extends Request = Request> = {
+    /**
+     * Validation custom message
+     */
+    validate?: Middleware<TRequest>;
+    /**
+     * Define what should be validated
+     * If not passed, it will be validating only body and query
+     */
+    validating?: ("body" | "query" | "params" | "headers")[];
+    /**
+     * Validation schema
+     */
+    schema?: ObjectValidator;
+};
+export interface RequestControllerContract {
+    /**
+     * Request object
+     */
+    request: Request;
+    /**
+     * Response object
+     */
+    response: Response;
+    /**
+     * Request Handler execution
+     */
+    execute(): Promise<ReturnedResponse>;
+    /**
+     * Request description
+     */
+    description?: string;
+    /**
+     * Request validation middleware
+     */
+    middleware?: () => Promise<MiddlewareResponse> | MiddlewareResponse;
+}
+export type RequestHandler<TRequest extends Request = Request> = {
+    /**
+     * Function Declaration
+     */
+    (request: TRequest, response: Response): ReturnedResponse | void;
+    /**
+     * Validation static object property which can be optional
+     */
+    validation?: RequestHandlerValidation<TRequest>;
+    /**
+     * Request Handler Description
+     */
+    description?: string;
+    /**
+     * Response schema for documentation / OpenAPI generation.
+     * Keyed by HTTP status code. Each entry declares the expected response body shape.
+     */
+    responseSchema?: ResponseSchema;
+};
+export interface RouteOptions {
+    /**
+     * Route middleware
+     */
+    middleware?: Middleware[];
+    /**
+     * Middleware precedence to be applied before grouped middleware or after it
+     */
+    middlewarePrecedence?: "before" | "after";
+    /**
+     * Route name
+     */
+    name?: string;
+    /**
+     * Route description
+     * Could be used for generating documentation
+     */
+    description?: string;
+    /**
+     * Request server options
+     */
+    serverOptions?: RouteShorthandOptions;
+    /**
+     * Set route label
+     * Will be used for generating documentation
+     * If not set, then Warlock will try to generate a label from the route path
+     */
+    label?: string;
+    /**
+     * Whether it is part of restful routes
+     */
+    restful?: boolean;
+    /**
+     * Mark this route as a page route that will be handled by React SSR
+     */
+    isPage?: boolean;
+    /**
+     * Rate limit options for this route
+     */
+    rateLimit?: {
+        /**
+         * Max number of requests within the time window
+         */
+        max: number;
+        /**
+         * Time window in milliseconds
+         */
+        timeWindow: number;
+        /**
+         * Error message when rate limit is exceeded
+         */
+        errorMessage?: string;
+    };
+}
+export type RequestMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD" | "all";
+/**
+ * Route Object
+ */
+export type Route = RouteOptions & {
+    /**
+     * Route method
+     */
+    method: RequestMethod;
+    /**
+     * Route source file (Relative path)
+     */
+    sourceFile: string;
+    /**
+     * Route path
+     */
+    path: string;
+    /**
+     * Route handler Can be a function
+     * And als can have a `validation` object as a static property of the handler
+     */
+    handler: RequestHandler;
+    /**
+     * Path prefix
+     * Kindly note the prefix is auto added by the router and it should be added to the path itself
+     * this will be used for generating the documentation
+     */
+    $prefix: string;
+    /**
+     * Path prefix Stack
+     * Kindly note the prefix is auto added by the router and it should be added to the path itself
+     * this will be used for generating the documentation
+     */
+    $prefixStack: string[];
+    /**
+     * Rate limit
+     */
+    rateLimit?: RouteOptions["rateLimit"];
+};
+export type PartialPick<T, F extends keyof T> = Omit<T, F> & Partial<Pick<T, F>>;
+/**
+ * Grouped routes options
+ */
+export type GroupedRoutesOptions = {
+    /**
+     * Middlewares to be applied to all routes
+     */
+    middleware?: Middleware[];
+    /**
+     * Route prefix
+     */
+    prefix?: string;
+    /**
+     * Route name
+     * This will be added to each route as a name prefix
+     */
+    name?: string;
+};
+/** Route resource */
+export type RouteResource = {
+    /**
+     * list route
+     */
+    list?: RequestHandler;
+    /**
+     * Single resource route
+     */
+    get?: RequestHandler;
+    /**
+     * Create resource route
+     */
+    create?: RequestHandler;
+    /**
+     * Update resource route
+     */
+    update?: RequestHandler;
+    /**
+     * Patch resource route
+     */
+    patch?: RequestHandler;
+    /**
+     * Delete resource route
+     */
+    delete?: RequestHandler;
+    /**
+     * Delete Multiple Records
+     */
+    bulkDelete?: RequestHandler;
+    /**
+     * Validation object
+     */
+    validation?: {
+        /**
+         * Apply validation on create|update|patch combined
+         */
+        all?: RequestHandlerValidation<any>;
+        /**
+         * Create validation object
+         */
+        create?: RequestHandlerValidation<any>;
+        /**
+         * Update validation object
+         */
+        update?: RequestHandlerValidation<any>;
+        /**
+         * Patch validation object
+         */
+        patch?: RequestHandlerValidation<any>;
+    };
+};
+export type RouterStacks = {
+    prefix: string[];
+    name: string[];
+    middleware: Middleware[];
+    /**
+     * Source file path for routes being added (for HMR route tracking)
+     */
+    sourceFile?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/esm/router/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/router/types.ts"],"names":[],"mappings":"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"}

package/esm/storage/config.d.ts

@@ -0,0 +1,15 @@
+import { S3ClientConfig } from "@aws-sdk/client-s3";
+import type { CloudStorageDriverOptions, LocalStorageDriverOptions, R2StorageDriverOptions, StorageConfigurations, StorageDriverConfig } from "./types";
+/**
+ * Get storage configuration
+ */
+export declare function storageConfig(): StorageConfigurations;
+export declare function storageConfig<T = any>(key: string): T;
+export declare function storageConfig<T = any>(key: string, defaultValue: T): T;
+export declare const storageConfigurations: {
+    local: (options: LocalStorageDriverOptions) => StorageDriverConfig;
+    aws: (options: CloudStorageDriverOptions & S3ClientConfig) => StorageDriverConfig;
+    r2: (options: R2StorageDriverOptions & S3ClientConfig) => StorageDriverConfig;
+    spaces: (options: CloudStorageDriverOptions & S3ClientConfig) => StorageDriverConfig;
+};
+//# sourceMappingURL=config.d.ts.map

package/esm/storage/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/storage/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EACzB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAgB,aAAa,IAAI,qBAAqB,CAAC;AACvD,wBAAgB,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;AACvD,wBAAgB,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC;AASxE,eAAO,MAAM,qBAAqB;qBACf,yBAAyB,KAAG,mBAAmB;mBAMjD,yBAAyB,GAAG,cAAc,KAAG,mBAAmB;kBAMjE,sBAAsB,GAAG,cAAc,KAAG,mBAAmB;sBAMzD,yBAAyB,GAAG,cAAc,KAAG,mBAAmB;CAMnF,CAAC"}

package/esm/storage/config.js

@@ -0,0 +1,32 @@
+import {config}from'../config/config-getter.js';import'../config/config-handlers.js';function storageConfig(key, defaultValue) {
+    if (!key) {
+        return config.get("storage");
+    }
+    return config.get(`storage.${key}`, defaultValue);
+}
+const storageConfigurations = {
+    local: (options) => {
+        return {
+            driver: "local",
+            ...options,
+        };
+    },
+    aws: (options) => {
+        return {
+            driver: "s3",
+            ...options,
+        };
+    },
+    r2: (options) => {
+        return {
+            driver: "r2",
+            ...options,
+        };
+    },
+    spaces: (options) => {
+        return {
+            driver: "spaces",
+            ...options,
+        };
+    },
+};export{storageConfig,storageConfigurations};//# sourceMappingURL=config.js.map

package/esm/storage/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sources":["../../src/storage/config.ts"],"sourcesContent":[null],"names":[],"mappings":"qFAgBgB,SAAA,aAAa,CAAC,GAAY,EAAE,YAAkB,EAAA;IAC5D,IAAI,CAAC,GAAG,EAAE;AACR,QAAA,OAAO,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9B,KAAA;IAED,OAAO,MAAM,CAAC,GAAG,CAAC,CAAA,QAAA,EAAW,GAAG,CAAE,CAAA,EAAE,YAAY,CAAC,CAAC;AACpD,CAAC;AAEY,MAAA,qBAAqB,GAAG;AACnC,IAAA,KAAK,EAAE,CAAC,OAAkC,KAAyB;QACjE,OAAO;AACL,YAAA,MAAM,EAAE,OAAO;AACf,YAAA,GAAG,OAAO;SACX,CAAC;KACH;AACD,IAAA,GAAG,EAAE,CAAC,OAAmD,KAAyB;QAChF,OAAO;AACL,YAAA,MAAM,EAAE,IAAI;AACZ,YAAA,GAAG,OAAO;SACX,CAAC;KACH;AACD,IAAA,EAAE,EAAE,CAAC,OAAgD,KAAyB;QAC5E,OAAO;AACL,YAAA,MAAM,EAAE,IAAI;AACZ,YAAA,GAAG,OAAO;SACX,CAAC;KACH;AACD,IAAA,MAAM,EAAE,CAAC,OAAmD,KAAyB;QACnF,OAAO;AACL,YAAA,MAAM,EAAE,QAAQ;AAChB,YAAA,GAAG,OAAO;SACX,CAAC;KACH;"}

package/esm/storage/context/storage-driver-context.d.ts

@@ -0,0 +1,69 @@
+import { Context } from "@warlock.js/context";
+import type { StorageDriverContract } from "../types";
+export type StorageDriverContextStore = {
+    driver?: StorageDriverContract;
+    prefix?: string;
+    metadata?: Record<string, any>;
+};
+/**
+ * Storage Driver Context
+ *
+ * Manages the active storage driver and path prefix using AsyncLocalStorage.
+ * Allows multi-tenant applications to switch drivers and isolate storage paths per request context.
+ *
+ * @example
+ * ```typescript
+ * // Set driver with tenant-specific prefix
+ * storageDriverContext.setDriver(storage.getDriver("s3"), {
+ *   prefix: "tenant-123",
+ *   metadata: { tenantId: "123" }
+ * });
+ *
+ * // Or just set prefix for same driver
+ * storageDriverContext.setPrefix("tenant-456");
+ * ```
+ */
+declare class StorageDriverContext extends Context<StorageDriverContextStore> {
+    /**
+     * Get the current storage driver
+     */
+    getDriver(): StorageDriverContract | undefined;
+    /**
+     * Get the current path prefix (e.g., tenant-specific path)
+     */
+    getPrefix(): string | undefined;
+    /**
+     * Get context metadata (e.g., tenantId)
+     */
+    getMetadata(): Record<string, any> | undefined;
+    /**
+     * Set the active driver with optional prefix and metadata
+     *
+     * @param driver - Storage driver to use
+     * @param options - Optional prefix and metadata
+     */
+    setDriver(driver: StorageDriverContract, options?: {
+        prefix?: string;
+        metadata?: Record<string, any>;
+    }): void;
+    /**
+     * Set only the path prefix (keeps current driver)
+     *
+     * Useful for multi-tenant scenarios where you want to isolate
+     * storage paths without changing the driver.
+     *
+     * @param prefix - Path prefix to prepend to all operations
+     */
+    setPrefix(prefix: string): void;
+    /**
+     * Clear the prefix
+     */
+    clearPrefix(): void;
+    /**
+     * Build the initial storage store with defaults
+     */
+    buildStore(): StorageDriverContextStore;
+}
+export declare const storageDriverContext: StorageDriverContext;
+export {};
+//# sourceMappingURL=storage-driver-context.d.ts.map

package/esm/storage/context/storage-driver-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-driver-context.d.ts","sourceRoot":"","sources":["../../../src/storage/context/storage-driver-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,oBAAqB,SAAQ,OAAO,CAAC,yBAAyB,CAAC;IACnE;;OAEG;IACI,SAAS,IAAI,qBAAqB,GAAG,SAAS;IAIrD;;OAEG;IACI,SAAS,IAAI,MAAM,GAAG,SAAS;IAItC;;OAEG;IACI,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAIrD;;;;;OAKG;IACI,SAAS,CACd,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAC5D,IAAI;IAQP;;;;;;;OAOG;IACI,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAItC;;OAEG;IACI,WAAW,IAAI,IAAI;IAI1B;;OAEG;IACI,UAAU,IAAI,yBAAyB;CAO/C;AAED,eAAO,MAAM,oBAAoB,sBAA6B,CAAC"}

package/esm/storage/context/storage-driver-context.js

@@ -0,0 +1,80 @@
+import {contextManager,Context}from'@warlock.js/context';/**
+ * Storage Driver Context
+ *
+ * Manages the active storage driver and path prefix using AsyncLocalStorage.
+ * Allows multi-tenant applications to switch drivers and isolate storage paths per request context.
+ *
+ * @example
+ * ```typescript
+ * // Set driver with tenant-specific prefix
+ * storageDriverContext.setDriver(storage.getDriver("s3"), {
+ *   prefix: "tenant-123",
+ *   metadata: { tenantId: "123" }
+ * });
+ *
+ * // Or just set prefix for same driver
+ * storageDriverContext.setPrefix("tenant-456");
+ * ```
+ */
+class StorageDriverContext extends Context {
+    /**
+     * Get the current storage driver
+     */
+    getDriver() {
+        return this.get("driver");
+    }
+    /**
+     * Get the current path prefix (e.g., tenant-specific path)
+     */
+    getPrefix() {
+        return this.get("prefix");
+    }
+    /**
+     * Get context metadata (e.g., tenantId)
+     */
+    getMetadata() {
+        return this.get("metadata");
+    }
+    /**
+     * Set the active driver with optional prefix and metadata
+     *
+     * @param driver - Storage driver to use
+     * @param options - Optional prefix and metadata
+     */
+    setDriver(driver, options) {
+        this.update({
+            driver,
+            prefix: options?.prefix,
+            metadata: options?.metadata,
+        });
+    }
+    /**
+     * Set only the path prefix (keeps current driver)
+     *
+     * Useful for multi-tenant scenarios where you want to isolate
+     * storage paths without changing the driver.
+     *
+     * @param prefix - Path prefix to prepend to all operations
+     */
+    setPrefix(prefix) {
+        this.update({ prefix });
+    }
+    /**
+     * Clear the prefix
+     */
+    clearPrefix() {
+        this.update({ prefix: undefined });
+    }
+    /**
+     * Build the initial storage store with defaults
+     */
+    buildStore() {
+        return {
+            driver: undefined,
+            prefix: undefined,
+            metadata: undefined,
+        };
+    }
+}
+const storageDriverContext = new StorageDriverContext();
+contextManager.register("storage", storageDriverContext);export{storageDriverContext};//# sourceMappingURL=storage-driver-context.js.map

package/esm/storage/context/storage-driver-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-driver-context.js","sources":["../../../src/storage/context/storage-driver-context.ts"],"sourcesContent":[null],"names":[],"mappings":"yDASA;;;;;;;;;;;;;;;;;AAiBG;AACH,MAAM,oBAAqB,SAAQ,OAAkC,CAAA;AACnE;;AAEG;IACI,SAAS,GAAA;AACd,QAAA,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;KAC3B;AAED;;AAEG;IACI,SAAS,GAAA;AACd,QAAA,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;KAC3B;AAED;;AAEG;IACI,WAAW,GAAA;AAChB,QAAA,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;KAC7B;AAED;;;;;AAKG;IACI,SAAS,CACd,MAA6B,EAC7B,OAA6D,EAAA;QAE7D,IAAI,CAAC,MAAM,CAAC;YACV,MAAM;YACN,MAAM,EAAE,OAAO,EAAE,MAAM;YACvB,QAAQ,EAAE,OAAO,EAAE,QAAQ;AAC5B,SAAA,CAAC,CAAC;KACJ;AAED;;;;;;;AAOG;AACI,IAAA,SAAS,CAAC,MAAc,EAAA;AAC7B,QAAA,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;KACzB;AAED;;AAEG;IACI,WAAW,GAAA;QAChB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;KACpC;AAED;;AAEG;IACI,UAAU,GAAA;QACf,OAAO;AACL,YAAA,MAAM,EAAE,SAAS;AACjB,YAAA,MAAM,EAAE,SAAS;AACjB,YAAA,QAAQ,EAAE,SAAS;SACpB,CAAC;KACH;AACF,CAAA;AAEY,MAAA,oBAAoB,GAAG,IAAI,oBAAoB,GAAG;AAE/D,cAAc,CAAC,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC"}

package/esm/storage/drivers/cloud-driver.d.ts

@@ -0,0 +1,206 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { Readable } from "stream";
+import type { CloudStorageDriverContract, CloudStorageDriverOptions, CloudStorageFileData, DeleteManyResult, FileVisibility, ListOptions, PresignedOptions, PresignedUploadOptions, PutOptions, StorageDriverType, StorageFileInfo } from "../types";
+/**
+ * Load S3 modules lazily
+ *
+ * @example
+ * await loadS3();
+ * if (isModuleExists) {
+ *   // Safe to use S3Client, S3Storage, S3Presigner
+ * }
+ */
+export declare function loadS3(): Promise<void>;
+/**
+ * Base abstract class for all S3-compatible cloud storage drivers
+ *
+ * This class contains all shared logic for S3-compatible storage services
+ * including AWS S3, Cloudflare R2, DigitalOcean Spaces, and others.
+ *
+ * **Important:** S3 SDK packages are lazy-loaded on first use.
+ * Users must install them separately:
+ * ```
+ * npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
+ * ```
+ *
+ * Subclasses must implement:
+ * - `name`: Driver identifier (e.g., "s3", "r2", "spaces")
+ * - `url()`: Returns the public URL for a file (provider-specific format)
+ */
+export declare abstract class CloudDriver<TOptions extends Partial<CloudStorageDriverOptions> = CloudStorageDriverOptions> implements CloudStorageDriverContract {
+    options: TOptions;
+    /**
+     * S3-compatible client (lazy-loaded)
+     */
+    protected client: InstanceType<typeof import("@aws-sdk/client-s3").S3Client>;
+    /**
+     * Retry configuration
+     */
+    protected retryConfig: {
+        maxRetries: number;
+        initialDelayMs: number;
+        maxDelayMs: number;
+        backoffMultiplier: number;
+    };
+    constructor(options: TOptions);
+    /**
+     * Driver name identifier
+     */
+    abstract readonly name: StorageDriverType;
+    /**
+     * Get public URL for file
+     * Must be implemented by subclasses with provider-specific format
+     */
+    abstract url(location: string): string;
+    /**
+     * Get endpoint URL
+     * Can be overridden by subclasses for provider-specific endpoints
+     */
+    protected getEndpoint(): string | undefined;
+    /**
+     * Apply prefix to location path
+     *
+     * Priority: context prefix > driver options prefix > no prefix
+     * This allows multi-tenant scenarios where context overrides driver config.
+     *
+     * @param location - Original location path
+     * @returns Location with prefix applied if one exists
+     */
+    applyPrefix(location: string): string;
+    /**
+     * Normalize storage path (remove double slashes, sanitize)
+     * @internal
+     */
+    protected normalizePath(path: string): string;
+    /**
+     * Execute an operation with retry logic
+     *
+     * Retries on transient errors with exponential backoff.
+     *
+     * @param operation - Async operation to execute
+     * @param operationName - Name for logging
+     * @returns Result of the operation
+     * @internal
+     */
+    protected withRetry<T>(operation: () => Promise<T>, operationName?: string): Promise<T>;
+    /**
+     * Check if an error is retryable
+     *
+     * Retries on:
+     * - Network errors
+     * - 5xx server errors
+     * - Rate limiting (429)
+     * - Timeout errors
+     *
+     * Does NOT retry on:
+     * - 4xx client errors (except 429)
+     * - Authentication errors
+     * - Not found errors
+     *
+     * @param error - Error to check
+     * @returns true if error is retryable
+     * @internal
+     */
+    protected isRetryableError(error: any): boolean;
+    /**
+     * Put file to cloud storage
+     */
+    put(file: Buffer, location: string, options?: PutOptions): Promise<CloudStorageFileData>;
+    /**
+     * Put file from a readable stream (for large files)
+     * Uses S3 multipart upload for efficient streaming
+     */
+    putStream(stream: Readable, location: string, options?: PutOptions): Promise<CloudStorageFileData>;
+    /**
+     * Get file contents as Buffer
+     */
+    get(location: string): Promise<Buffer>;
+    /**
+     * Get file as a readable stream (for large files)
+     */
+    getStream(location: string): Promise<Readable>;
+    /**
+     * Delete a file
+     */
+    delete(location: string): Promise<boolean>;
+    /**
+     * Delete multiple files at once (uses batch delete for efficiency)
+     */
+    deleteMany(locations: string[]): Promise<DeleteManyResult[]>;
+    /**
+     * Delete directory (recursively deletes all objects with matching prefix)
+     *
+     * S3/R2 doesn't have true directories - only key prefixes.
+     * This method lists all objects with the prefix and deletes them in batches.
+     *
+     * @param directoryPath - Directory prefix to delete
+     * @returns true when all objects are deleted
+     */
+    deleteDirectory(directoryPath: string): Promise<boolean>;
+    /**
+     * Check if file exists
+     */
+    exists(location: string): Promise<boolean>;
+    /**
+     * Get a temporary presigned URL (alias for getPresignedUrl)
+     */
+    temporaryUrl(location: string, expiresIn?: number): Promise<string>;
+    /**
+     * Get presigned URL for downloading
+     */
+    getPresignedUrl(location: string, options?: PresignedOptions): Promise<string>;
+    /**
+     * Get presigned URL for uploading
+     */
+    getPresignedUploadUrl(location: string, options?: PresignedUploadOptions): Promise<string>;
+    /**
+     * Get file info/metadata without downloading
+     */
+    getInfo(location: string): Promise<StorageFileInfo>;
+    /**
+     * Get file size in bytes (shortcut for getInfo().size)
+     */
+    size(location: string): Promise<number>;
+    /**
+     * Copy file to a new location
+     */
+    copy(from: string, to: string): Promise<CloudStorageFileData>;
+    /**
+     * Move file to a new location
+     */
+    move(from: string, to: string): Promise<CloudStorageFileData>;
+    /**
+     * List files in a directory
+     */
+    list(directory: string, options?: ListOptions): Promise<StorageFileInfo[]>;
+    /**
+     * Get bucket name
+     */
+    getBucket(): string;
+    /**
+     * Get region
+     */
+    getRegion(): string;
+    /**
+     * Set storage class (e.g., STANDARD, GLACIER, etc.)
+     */
+    setStorageClass(location: string, storageClass: string): Promise<void>;
+    /**
+     * Set file visibility (public or private)
+     */
+    setVisibility(location: string, visibility: FileVisibility): Promise<void>;
+    /**
+     * Get file visibility
+     */
+    getVisibility(location: string): Promise<FileVisibility>;
+    /**
+     * Calculate SHA-256 hash
+     */
+    protected calculateHash(buffer: Buffer): string;
+    /**
+     * Guess MIME type from file extension
+     */
+    protected guessMimeType(location: string): string;
+}
+//# sourceMappingURL=cloud-driver.d.ts.map