import type { Buffer } from 'node:buffer';
/**
 * Helper to create async iterable from array
 */
export declare function createDirectoryListing(entries: DirectoryEntry[]): DirectoryListing;
/**
 * Convert expiry to milliseconds
 */
export declare function normalizeExpiryToMilliseconds(expiry: number | Date): number;
/**
 * Convert expiry to Date
 */
export declare function normalizeExpiryToDate(expiry: number | Date): Date;
/**
 * Check if entry is a file
 */
export declare function isFile(entry: DirectoryEntry | StatEntry): boolean;
/**
 * Check if entry is a directory
 */
export declare function isDirectory(entry: DirectoryEntry | StatEntry): boolean;
/**
 * File stat entry information
 */
export declare interface StatEntry {
  path: string
  type: 'file' | 'directory'
  visibility: Visibility
  size: number
  lastModified: number
  mimeType?: string
  metadata?: Record<string, any>
}
/**
 * Options for `Storage.getStream(path, options?)`
 * (stacksjs/stacks#1886).
 */
export declare interface GetStreamOptions {
  signal?: AbortSignal
}
/**
 * Options for `Storage.putStream(path, stream, options?)`
 * (stacksjs/stacks#1886). All fields are optional; the S3 driver
 * reads them to tune its multipart pipeline, other drivers
 * generally only honor `contentType` and `signal`.
 */
export declare interface PutStreamOptions {
  contentType?: string
  signal?: AbortSignal
  partSize?: number
  concurrency?: number
  maxRetries?: number
}
/**
 * Result returned from `Storage.put()` (stacksjs/stacks#1888 S-8).
 *
 * Pre-fix `put()` returned `Promise<void>` — callers that wanted to
 * record an etag for cache-invalidation or a size for storage-quota
 * accounting had to issue a second `.stat()` round-trip. This shape
 * carries the metadata back from the write itself.
 *
 * Fields beyond `path` are best-effort: drivers that don't expose
 * (or can't cheaply compute) a value omit it rather than synthesizing
 * a fake one. Callers should treat them as nullable.
 */
export declare interface PutResult {
  path: string
  size: number
  contentType?: string
  lastModified?: number
  etag?: string
}
/**
 * Directory listing entry
 */
export declare interface DirectoryEntry {
  path: string
  type: 'file' | 'directory'
}
/**
 * Directory listing iterator
 */
export declare interface DirectoryListing extends AsyncIterable<DirectoryEntry> {
  [Symbol.asyncIterator](): AsyncIterator<DirectoryEntry>
}
/**
 * Options for listing directories
 */
export declare interface ListOptions {
  deep?: boolean
}
/**
 * Options for generating public URLs
 */
export declare interface PublicUrlOptions {
  domain?: string
}
/**
 * Options for generating temporary URLs
 */
export declare interface TemporaryUrlOptions {
  expiresIn: number | Date
}
/**
 * Options for generating signed (JWT-style) URLs.
 *
 * Distinct from `TemporaryUrlOptions` so adapters that don't natively
 * support the richer claims set (in-memory mocks) can throw a clear
 * "unsupported" error rather than silently returning a useless URL.
 */
export declare interface SignedUrlOptions {
  expiresIn: number | Date
  issuer?: string
  baseUrl?: string
}
/**
 * Options for `presignedUploadPolicy()` — the POST-form upload
 * primitive that S3 can enforce server-side (stacksjs/stacks#1888
 * Phase B). Distinct from {@link PresignedUploadUrlOptions} (PUT-
 * form): the POST policy carries a `Content-Length-Range` condition
 * that S3 enforces server-side, so this is the right primitive when
 * you genuinely need a size cap against an untrusted client.
 */
export declare interface PresignedUploadPolicyOptions {
  key: string | { startsWith: string }
  contentType: string | { startsWith: string }
  contentLengthRange?: { min: number, max: number }
  acl?: 'private' | 'public-read' | 'public-read-write' | 'authenticated-read' | 'bucket-owner-read' | 'bucket-owner-full-control'
  expiresIn: number
  fields?: Record<string, string>
}
/**
 * What the caller hands to the browser. Submit as
 * `multipart/form-data` to `url` with every entry of `fields` as a
 * form field, then the actual file LAST under the field name
 * `'file'`. `key` is what the upload will land at — store on the
 * domain record.
 */
export declare interface PresignedUploadPolicy {
  url: string
  fields: Record<string, string>
  key: string
}
/**
 * Options for `presignedUploadUrl()` (stacksjs/stacks#1856 Stage 6).
 */
export declare interface PresignedUploadUrlOptions {
  contentType: string
  expiresIn: number
  dir?: string
  filename?: string
  maxBytes?: number
}
export declare interface PresignedUploadUrl {
  url: string
  path: string
  key: string
  contentType: string
  maxBytes?: number
}
/**
 * Checksum algorithm options
 */
export declare interface ChecksumOptions {
  algorithm?: 'md5' | 'sha1' | 'sha256'
}
/**
 * MIME type detection options
 */
export declare interface MimeTypeOptions {
  useExtension?: boolean
}
/**
 * Storage adapter configuration
 */
export declare interface StorageAdapterConfig {
  root?: string
  url?: string
  bucket?: string
  region?: string
  prefix?: string
  endpoint?: string
  usePathStyleEndpoint?: boolean
  credentials?: {
    accessKeyId: string
    secretAccessKey: string
    sessionToken?: string
  }
}
/**
 * Base storage adapter interface
 */
export declare interface StorageAdapter {
  write(path: string, contents: FileContents): Promise<PutResult>
  read(path: string): Promise<FileContents>
  readToString(path: string): Promise<string>
  readToBuffer(path: string): Promise<Buffer>
  readToUint8Array(path: string): Promise<Uint8Array>
  deleteFile(path: string): Promise<void>
  deleteDirectory(path: string): Promise<void>
  createDirectory(path: string): Promise<void>
  moveFile(from: string, to: string): Promise<void>
  copyFile(from: string, to: string): Promise<void>
  stat(path: string): Promise<StatEntry>
  list(path: string, options?: ListOptions): DirectoryListing
  changeVisibility(path: string, visibility: Visibility): Promise<void>
  visibility(path: string): Promise<Visibility>
  fileExists(path: string): Promise<boolean>
  directoryExists(path: string): Promise<boolean>
  publicUrl(path: string, options?: PublicUrlOptions): Promise<string>
  temporaryUrl(path: string, options: TemporaryUrlOptions): Promise<string>
  signedUrl?(path: string, options: SignedUrlOptions): Promise<string>
  presignedUploadUrl?(options: PresignedUploadUrlOptions): Promise<PresignedUploadUrl>
  presignedUploadPolicy?(options: PresignedUploadPolicyOptions): Promise<PresignedUploadPolicy>
  getStream?(path: string, options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>
  putStream?(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>
  checksum(path: string, options?: ChecksumOptions): Promise<string>
  mimeType(path: string, options?: MimeTypeOptions): Promise<string>
  lastModified(path: string): Promise<number>
  fileSize(path: string): Promise<number>
}
/**
 * File contents can be a string, Buffer, Uint8Array, or ReadableStream
 */
export type FileContents = string | Buffer | Uint8Array | ReadableStream;
/**
 * Visibility options for files
 */
export declare enum Visibility {
  PUBLIC = 'public',
  PRIVATE = 'private',
}