<!--
hoody-files Subskill (sdk)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-20T00:05:05.213Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: sdk


Tokens: 32507

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

```
# hoody-files Subskill

## Overview

### Service Purpose

hoody-files is the universal file access service in Hoody Kit. It provides a unified interface to manage files across local storage and 60+ cloud storage providers. Every file path is a URL, enabling seamless file operations regardless of storage backend.

### When to Use This Service

Use hoody-files when you need to:

- **Manage files** on a Hoody container (upload, download, copy, move, delete, search)
- **Connect cloud storage** backends (S3, Google Drive, Dropbox, OneDrive, Azure, etc.)
- **Process archives** (ZIP, TAR extraction and creation)
- **Mount remote filesystems** via FUSE for direct OS-level access
- **Transform images** on-the-fly (resize, format conversion, effects)
- **Search file contents** using regex (grep) or glob patterns
- **Track file operations** via the mutation journal
- **Access remote files** via SSH, FTP, Git, WebDAV, or S3 protocols

### Authentication Model

All requests to hoody-files are authenticated through the Hoody Proxy routing system. The service URL pattern is:

```
https://{projectId}-{containerId}-files-{serviceId}.{node}.containers.hoody.com
```

Authentication is handled automatically by the Hoody SDK when you use `HoodyClient`. No manual token management is required for file operations.

### How It Fits Into Hoody Philosophy

hoody-files embodies Hoody's philosophy of universal, provider-agnostic access. Rather than managing separate integrations for each cloud provider, you connect backends once and operate on files uniformly. The service abstracts away provider-specific APIs, authentication flows, and storage semantics into a single, consistent interface.

### SDK Setup

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

// Authenticate with Hoody API
const client = await HoodyClient.authenticate('https://api.hoody.com', {
  username: 'your-username',
  password: 'your-password'
})
```

All file operations use `client.files.*` with nested sub-namespaces for logical grouping.

---

## Core Resource Workflows

### 1. File Operations (Basic CRUD)

The fundamental file operations support reading, writing, and managing files on the container.

#### List Directory Contents

```
// List files in a directory (returns JSON listing)
const listing = await client.files.listDirectory('path/to/directory', { json: 'true' })

// List with sorting options
const sorted = await client.files.listDirectory('path/to/directory', {
  json: 'true',
  sort: 'name',
  order: 'asc'
})

// List with file hashes
const withHashes = await client.files.listDirectory('path/to/directory', {
  json: 'true',
  hash: 'sha256'
})
```

Expected response for directory listing:

```
{
  "entries": [
    {
      "name": "file.txt",
      "path": "path/to/directory/file.txt",
      "size": 1024,
      "modTime": "2025-01-15T10:30:00Z",
      "type": "file"
    }
  ],
  "total": 1,
  "directory": "path/to/directory"
}
```

#### Download a File

```
// Download file (triggers Content-Disposition: attachment)
const file = await client.files.get('path/to/file.txt', {
  download: 'true'
})

// Download with specific content type
const pdf = await client.files.get('documents/report.pdf', {
  download: 'true',
  'content-type': 'application/pdf'
})
```

#### Upload a File

```
// Upload a new file or overwrite existing
const result = await client.files.upload({ path: 'path/to/new-file.txt' })

// Append to existing file instead of overwriting
const appended = await client.files.put('path/to/log.txt', { append: 'true' })
```

Expected response for upload:

```
{
  "path": "path/to/new-file.txt",
  "size": 2048,
  "modified": "2025-01-15T12:00:00Z"
}
```

#### Append Data to File

```
// Append binary data to end of file (creates if not exists)
const result = await client.files.append({ path: 'path/to/log.txt' })

// With owner specification
const result2 = await client.files.append('path/to/log.txt', { owner: 'user:group' })
```

Expected response for append:

```
{
  "appended": true,
  "size": 4096,
  "path": "path/to/log.txt"
}
```

#### Get File Metadata (HEAD)

```
// Get file metadata without downloading content
const metadata = await client.files.getMetadata({ path: 'path/to/file.txt' })

// Get metadata with version history
const historyMeta = await client.files.getMetadata('path/to/file.txt', {
  history: 'true',
  limit: 10
})
```

#### Delete File or Directory

```
// Delete a single file
await client.files.deleteRecursive({ path: 'path/to/file.txt' })

// Delete a directory recursively
await client.files.deleteRecursive({ path: 'path/to/directory' })
```

#### Touch File (Create or Update mtime)

```
// Create empty file or update modification time
await client.files.touch({ path: 'path/to/empty-file.txt', touch: 'true' })
```

Expected response for touch:

```
{
  "path": "path/to/empty-file.txt",
  "created": true,
  "modTime": "2025-01-15T14:00:00Z"
}
```

#### Modify File via PATCH

```
// Rename a file via JSON body
await client.files.patch('path/to/old-name.txt', {
  data: { name: 'new-name.txt' }
})

// Move file to different directory
await client.files.patch('path/to/file.txt', {
  data: { move_to: 'path/to/destination/' }
})

// Change permissions via query parameter
await client.files.patch('path/to/script.sh', undefined, { chmod: '755' })
```

---

### 2. File Operations (Advanced)

#### Append Data to File

```
// Append data to existing file
const result = await client.files.append({ path: 'logs/application.log' })

// With owner specification
const result2 = await client.files.append('data/output.csv', { owner: 'app:app' })
```

#### Change File Permissions (chmod)

```
// Set permissions to 755 (rwxr-xr-x)
const result = await client.files.chmod({ path: 'scripts/deploy.sh', chmod: '755' })

// Set permissions to 644 (rw-r--r--)
const result2 = await client.files.chmod({ path: 'config/settings.json', chmod: '644' })
```

Expected response for chmod:

```
{
  "chmod": true,
  "path": "scripts/deploy.sh",
  "mode": "755"
}
```

#### Change File Ownership (chown)

```
// Set owner and group
const result = await client.files.chown({ path: 'data/files/report.pdf', chown: 'www-data:www-data' })

// Set owner only (group optional)
const result2 = await client.files.chown({ path: 'data/uploads/image.png', chown: 'appuser' })
```

Expected response for chown:

```
{
  "chown": true,
  "path": "data/files/report.pdf",
  "owner": "www-data",
  "group": "www-data"
}
```

#### Copy File or Directory

```
// Copy file to new location
const result = await client.files.copy({ path: 'source/file.txt', copy_to: 'destination/file.txt' })

// Copy directory recursively
const result2 = await client.files.copy({ path: 'project/src', copy_to: 'project/backup/src' })

// Copy with overwrite enabled
const result3 = await client.files.copy('old/config.json', 'config/config.json', {
  overwrite: 'true'
})

// Copy with owner specification
const result4 = await client.files.copy('template.html', 'public/index.html', {
  owner: 'www-data'
})
```

Expected response for copy:

```
{
  "copied": true,
  "source": "source/file.txt",
  "destination": "destination/file.txt",
  "size": 1024
}
```

#### Move or Rename File/Directory

```
// Move file to new location
const result = await client.files.move({ path: 'temp/upload.tmp', move_to: 'data/processed/upload.csv' })

// Rename file in same directory
const result2 = await client.files.move({ path: 'logs/app.log', move_to: 'logs/app-2025-01-15.log' })

// Move with owner specification
const result3 = await client.files.move('incoming/data.json', 'archive/data.json', {
  owner: 'archive:archive'
})
```

Expected response for move:

```
{
  "moved": true,
  "source": "temp/upload.tmp",
  "destination": "data/processed/upload.csv"
}
```

#### Find Files by Glob Pattern

```
// Find all TypeScript files recursively
const results = await client.files.glob('project/src', {
  pattern: '**/*.ts'
})

// Find files with brace expansion
const configFiles = await client.files.glob('config', {
  pattern: '*.{json,yaml,yml,toml}'
})

// Find with depth and result limits
const limited = await client.files.glob('.', {
  pattern: '*.log',
  max_depth: 3,
  max_results: 50
})

// Find with timeout
const timedSearch = await client.files.glob('large-project', {
  pattern: '**/*.{js,jsx}',
  timeout: 30
})
```

Expected response for glob:

```
{
  "matches": [
    {
      "path": "project/src/index.ts",
      "name": "index.ts",
      "size": 2048,
      "modTime": "2025-01-15T10:00:00Z",
      "type": "file"
    },
    {
      "path": "project/src/utils/helpers.ts",
      "name": "helpers.ts",
      "size": 4096,
      "modTime": "2025-01-14T15:30:00Z",
      "type": "file"
    }
  ],
  "total": 2,
  "pattern": "**/*.ts"
}
```

#### Search File Contents (grep)

```
// Search for regex pattern in files
const results = await client.files.grep('src', {
  pattern: 'function\\s+\\w+\\('
})

// Case-insensitive search
const caseInsensitive = await client.files.grep('logs', {
  pattern: 'error|warning|critical',
  ignore_case: true
})

// Fixed string search (no regex)
const literal = await client.files.grep('config', {
  pattern: 'API_KEY',
  fixed_string: true
})

// Search with file glob filter
const jsOnly = await client.files.grep('.', {
  pattern: 'import.*from',
  glob: '*.{js,ts,jsx,tsx}'
})

// Search with context lines
const withContext = await client.files.grep('src', {
  pattern: 'TODO|FIXME|HACK',
  context: 2,
  max_count: 100
})
```

Expected response for grep:

```
{
  "matches": [
    {
      "path": "src/index.ts",
      "line_number": 42,
      "line": "export function processData(input: string): Result {",
      "context_before": ["import { Result } from './types';", ""],
      "context_after": ["  // Implementation", "  return transform(input);"]
    }
  ],
  "total_matches": 1,
  "files_searched": 15,
  "pattern": "function\\s+\\w+\\("
}
```

#### Resolve Canonical Path (realpath)

```
// Resolve symlinks and relative paths
const resolved = await client.files.realpath({ path: 'data/../config/./settings.json' })
```

Expected response for realpath:

```
{
  "path": "/home/user/config/settings.json",
  "resolved": true
}
```

#### Get File Metadata (stat)

```
// Get detailed file statistics
const stats = await client.files.stat({ path: 'path/to/file.txt' })

// Get directory statistics
const dirStats = await client.files.stat({ path: 'path/to/directory' })
```

Expected response for stat:

```
{
  "name": "file.txt",
  "path": "path/to/file.txt",
  "type": "file",
  "size": 1024,
  "modTime": "2025-01-15T10:30:00Z",
  "accessTime": "2025-01-15T10:35:00Z",
  "changeTime": "2025-01-15T10:30:00Z",
  "mode": "0644",
  "owner": "user",
  "group": "staff",
  "isSymlink": false,
  "inode": 12345678
}
```

#### File Operations via POST

```
// Create directory
await client.files.operate('new/directory', { mkdir: 'true' })

// Extract archive to destination
await client.files.operate('archive.zip', {
  extract: 'true',
  dest: 'extracted/'
})

// Download from URL
await client.files.operate('downloads/file.pdf', {
  download_from: 'https://example.com/document.pdf'
})

// Move file
await client.files.operate('source.txt', {
  move_to: 'destination/source.txt'
})

// Copy file
await client.files.operate('original.txt', {
  copy_to: 'backup/original.txt',
  overwrite: 'true'
})
```

#### Modify File Properties via PATCH (v1 API)

> **Note:** `patchApi` is the v1 form accepting flat options (e.g., `{ chmod: '755' }`). The legacy `patch` method wraps options in `{ data: {...} }`. Prefer `patchApi` for new code.

```
// Change permissions
await client.files.patchApi('path/to/file.txt', { chmod: '755' })

// Change ownership
await client.files.patchApi('path/to/file.txt', { chown: 'user:group' })

// Rename file
await client.files.patchApi('path/to/old-name.txt', {
  data: { name: 'new-name.txt' }
})

// Move to different directory
await client.files.patchApi('path/to/file.txt', {
  data: { move_to: 'new/location/' }
})
```

#### Delete via v1 API

```
// Delete file
await client.files.delete({ path: 'path/to/file.txt' })

// Delete from specific backend
await client.files.delete('remote/path/file.txt', { backend: 'my-s3-backend' })
```

---

### 3. Search Operations

#### Search Directory (Legacy API)

```
// Search for files matching query
const results = await client.files.search('project', { q: 'README' })

// Search with JSON response
const jsonResults = await client.files.search('src', {
  q: 'index',
  json: 'true'
})
```

Expected response for search:

```
{
  "query": "README",
  "directory": "project",
  "results": [
    {
      "path": "project/README.md",
      "name": "README.md",
      "type": "file",
      "size": 5120,
      "modTime": "2025-01-10T09:00:00Z"
    }
  ],
  "total": 1
}
```

---

### 4. Downloads Management

#### Get Download History

```
// Retrieve history of past downloads
const history = await client.files.downloads.getHistory({ download_history: 'example-download_history' })
```

Expected response for download history:

```
{
  "downloads": [
    {
      "url": "https://example.com/file.zip",
      "destination": "downloads/file.zip",
      "status": "completed",
      "size": 10485760,
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:02:30Z"
    }
  ],
  "total": 1
}
```

#### Download File from Remote URL

```
// Download a file from URL to server
const result = await client.files.downloads.fetch({ directory: 'downloads', download: 'https://example.com/data.tar.gz' })

// Download with custom filename
const result2 = await client.files.downloads.fetch('downloads', 'https://example.com/file.zip', 'custom-name.zip')

// Download with timeout
const result3 = await client.files.downloads.fetch('downloads', 'https://example.com/large.iso', undefined, 300)
```

Expected response for download:

```
{
  "download_id": "dl_abc123",
  "url": "https://example.com/data.tar.gz",
  "destination": "downloads/data.tar.gz",
  "status": "started"
}
```

#### List Active Downloads

```
// List all active downloads globally
const active = await client.files.downloads.listGlobal()

// List active downloads for specific directory
const dirActive = await client.files.downloads.listActive({ directory: 'downloads', downloads: 'example-downloads' })
```

Expected response for active downloads:

```
{
  "downloads": [
    {
      "download_id": "dl_abc123",
      "url": "https://example.com/large-file.iso",
      "destination": "downloads/large-file.iso",
      "status": "in_progress",
      "progress": 45.2,
      "bytes_downloaded": 536870912,
      "total_bytes": 1073741824,
      "speed": 10485760,
      "eta": 51
    }
  ],
  "total": 1
}
```

---

### 5. Archive Operations

#### Get Extraction History

```
// Retrieve history of past extractions
const history = await client.files.archives.getHistory({ extraction_history: 'example-extraction_history' })
```

Expected response for extraction history:

```
{
  "extractions": [
    {
      "archive": "data/archive.zip",
      "destination": "data/extracted/",
      "status": "completed",
      "files_extracted": 42,
      "total_size": 20971520,
      "started_at": "2025-01-15T11:00:00Z",
      "completed_at": "2025-01-15T11:01:15Z"
    }
  ],
  "total": 1
}
```

#### List Active Extractions

```
// List active extractions via query parameter
const activeQuery = await client.files.archives.listActive({ extractions: 'example-extractions' })

// List active extractions via v1 API
const activeApi = await client.files.archives.listGlobal()
```

Expected response for active extractions:

```
{
  "extractions": [
    {
      "extraction_id": "ext_xyz789",
      "archive": "backups/full-backup.tar.gz",
      "destination": "restore/",
      "status": "in_progress",
      "progress": 78.5,
      "files_processed": 156,
      "current_file": "restore/images/photo-2024.jpg"
    }
  ],
  "total": 1
}
```

#### Extract Archive

```
// Extract entire archive
const result = await client.files.archives.extract({ archive: 'uploads/project.zip', extract: 'extract' })

// Extract to specific destination
const result2 = await client.files.archives.extract('backups/data.tar.gz', 'extract', 'restored/data/')

// Selectively extract matching entries
const result3 = await client.files.archives.extract('src/archive.zip', 'extract', undefined, 'src/**/*.ts')
```

Expected response for extraction:

```
{
  "extraction_id": "ext_abc123",
  "archive": "uploads/project.zip",
  "destination": "extracted/",
  "status": "started",
  "files_to_extract": 25
}
```

#### Extract Single File from Archive

```
// Extract single file from archive
const result = await client.files.archives.extractFile('backups/data.tar.gz', 'extract_file', 'data/config.json')

// Extract to specific destination
const result2 = await client.files.archives.extractFile('archive.zip', 'extract_file', 'important.pdf', 'output/')
```

Expected response for single file extraction:

```
{
  "extraction_id": "ext_single_001",
  "archive": "backups/data.tar.gz",
  "extracted_file": "data/config.json",
  "destination": "output/data/config.json",
  "status": "completed",
  "size": 4096
}
```

#### Preview Archive Contents

```
// List all files in archive (JSON)
const contents = await client.files.archives.preview({ archive: 'uploads/project.zip' })

// Read specific file from archive without extraction
const fileContent = await client.files.archives.preview('backups/config.tar.gz', 'config/settings.json')
```

Expected response for archive preview (listing):

```
{
  "archive": "uploads/project.zip",
  "entries": [
    {
      "name": "index.js",
      "path": "src/index.js",
      "size": 2048,
      "modTime": "2025-01-10T08:00:00Z",
      "is_dir": false,
      "compressed_size": 1024
    },
    {
      "name": "utils",
      "path": "src/utils",
      "size": 0,
      "modTime": "2025-01-10T08:00:00Z",
      "is_dir": true,
      "compressed_size": 0
    }
  ],
  "total_entries": 2,
  "total_size": 2048,
  "compressed_size": 1024
}
```

#### View File from Archive

```
// View raw file content from archive
const content = await client.files.archives.viewFile({ archive: 'backup.tar.gz', preview: 'documents/report.txt' })
```

#### Download Directory as ZIP

```
// Download entire directory as ZIP archive
const zipData = await client.files.archives.downloadAsZip({ directory: 'project/src', zip: 'download' })
```

---

### 6. Backend Management (Cloud Storage Providers)

#### List All Backends

```
// Get all connected backends
const backends = await client.files.backends.list()
```

Expected response for backend listing:

```
{
  "backends": [
    {
      "id": "backend_s3_001",
      "type": "s3",
      "name": "My S3 Bucket",
      "status": "connected",
      "created_at": "2025-01-10T09:00:00Z",
      "last_used": "2025-01-15T14:30:00Z"
    },
    {
      "id": "backend_gdrive_002",
      "type": "drive",
      "name": "Google Drive",
      "status": "connected",
      "created_at": "2025-01-12T11:00:00Z",
      "last_used": "2025-01-15T10:15:00Z"
    }
  ],
  "total": 2
}
```

#### Connect S3 Backend

```
// Connect to AWS S3
const s3Backend = await client.files.backends.connectS3({
  name: 'production-backups',
  s3_provider: 'AWS',
  access_key_id: 'AKIAIOSFODNN7EXAMPLE',
  secret_access_key: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  region: 'us-east-1',
  endpoint: 'https://s3.amazonaws.com'
})

// Connect to MinIO
const minioBackend = await client.files.backends.connectS3({
  name: 'local-minio',
  s3_provider: 'Other',
  access_key_id: 'minioadmin',
  secret_access_key: 'minioadmin',
  region: 'us-east-1',
  endpoint: 'https://minio.example.com',
  force_path_style: true
})

// Connect to DigitalOcean Spaces
const doBackend = await client.files.backends.connectS3({
  name: 'do-spaces',
  s3_provider: 'DigitalOcean',
  access_key_id: 'your-spaces-key',
  secret_access_key: 'your-spaces-secret',
  region: 'nyc3',
  endpoint: 'https://nyc3.digitaloceanspaces.com'
})
```

#### Connect Google Drive Backend

```
// Connect to Google Drive (OAuth flow)
const driveBackend = await client.files.backends.connectDrive({
  name: 'company-drive',
  client_id: 'your-client-id.apps.googleusercontent.com',
  client_secret: 'your-client-secret',
  scope: 'drive',
  token: '{"access_token":"...","refresh_token":"...","token_type":"Bearer"}'
})
```

#### Connect Dropbox Backend

```
// Connect to Dropbox
const dropboxBackend = await client.files.backends.connectDropbox({
  name: 'team-dropbox',
  client_id: 'your-app-key',
  client_secret: 'your-app-secret',
  token: '{"access_token":"sl.xxx","token_type":"bearer"}'
})
```

#### Connect OneDrive Backend

```
// Connect to Microsoft OneDrive
const onedriveBackend = await client.files.backends.connectOnedrive({
  name: 'personal-onedrive',
  client_id: 'your-app-id',
  client_secret: 'your-app-secret',
  token: '{"access_token":"EwB...","refresh_token":"M.R3..."}'
})
```

#### Connect Azure Blob Storage Backend

```
// Connect to Azure Blob Storage
const azureBackend = await client.files.backends.connectAzureblob({
  name: 'azure-storage',
  account: 'yourstorageaccount',
  key: 'your-storage-key',
  endpoint: 'https://yourstorageaccount.blob.core.windows.net'
})
```

#### Connect Azure Files Backend

```
// Connect to Azure Files
const azureFilesBackend = await client.files.backends.connectAzurefiles({
  name: 'azure-files',
  account: 'yourstorageaccount',
  key: 'your-storage-key',
  share_name: 'myshare'
})
```

#### Connect SFTP Backend

```
// Connect to SFTP server
const sftpBackend = await client.files.backends.connectSftp({
  name: 'production-server',
  host: 'sftp.example.com',
  port: 22,
  user: 'deploy',
  pass: 'secure-password',
  key_file: '/path/to/private-key',
  key_file_pass: 'key-passphrase'
})
```

#### Connect FTP Backend

```
// Connect to FTP server
const ftpBackend = await client.files.backends.connectFtp({
  name: 'legacy-ftp',
  host: 'ftp.example.com',
  port: 21,
  user: 'ftpuser',
  pass: 'ftppassword',
  ftp_secure: false,
  ftp_passive: true
})
```

#### Connect WebDAV Backend

```
// Connect to WebDAV server (Nextcloud, ownCloud)
const webdavBackend = await client.files.backends.connectWebdav({
  name: 'nextcloud',
  url: 'https://cloud.example.com/remote.php/dav/files/user/',
  user: 'username',
  pass: 'password',
  vendor: 'nextcloud'
})
```

#### Connect Box Backend

```
// Connect to Box
const boxBackend = await client.files.backends.connectBox({
  name: 'enterprise-box',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: '{"access_token":"...","refresh_token":"..."}'
})
```

#### Connect pCloud Backend

```
// Connect to pCloud
const pcloudBackend = await client.files.backends.connectPcloud({
  name: 'pcloud-storage',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: '{"access_token":"..."}'
})
```

#### Connect Backblaze B2 Backend

```
// Connect to Backblaze B2
const b2Backend = await client.files.backends.connectB2({
  name: 'b2-archive',
  account: 'your-account-id',
  key: 'your-application-key'
})
```

#### Connect Google Cloud Storage Backend

```
// Connect to Google Cloud Storage
const gcsBackend = await client.files.backends.connectGoogleCloudStorage({
  name: 'gcs-bucket',
  project_number: '123456789',
  service_account_credentials: '{"type":"service_account","project_id":"..."}',
  location: 'us-central1'
})
```

#### Connect Storj Backend

```
// Connect to Storj DCS
const storjBackend = await client.files.backends.connectStorj({
  name: 'storj-decentralized',
  api_key: 'your-api-key',
  passphrase: 'your-passphrase',
  satellite_address: 'us1.storj.io:7777'
})
```

#### Connect MEGA Backend

```
// Connect to MEGA
const megaBackend = await client.files.backends.connectMega({
  name: 'mega-cloud',
  user: 'user@example.com',
  pass: 'your-password'
})
```

#### Connect OpenStack Swift Backend

```
// Connect to OpenStack Swift
const swiftBackend = await client.files.backends.connectSwift({
  name: 'rackspace-files',
  user: 'your-username',
  key: 'your-api-key',
  auth: 'https://identity.api.rackspacecloud.com/v2.0',
  tenant: 'your-tenant-id',
  region: 'IAD'
})
```

#### Connect Alias Backend

```
// Create alias pointing to existing backend path
const aliasBackend = await client.files.backends.connectAlias({
  name: 'backups-alias',
  remote: 'my-s3-backend:backups/daily/'
})
```

#### Connect Combine Backend

```
// Combine multiple backends into one
const combineBackend = await client.files.backends.connectCombine({
  name: 'all-storage',
  upstreams: 'local-storage s3-backend gdrive-backend'
})
```

#### Connect Union Backend

```
// Merge multiple filesystems
const unionBackend = await client.files.backends.connectUnion({
  name: 'unified-fs',
  upstreams: 'backend1: backend2: backend3:'
})
```

#### Connect Chunker Backend

```
// Chunk large files across backend
const chunkerBackend = await client.files.backends.connectChunker({
  name: 'chunked-s3',
  remote: 's3-backend:bucket',
  chunk_size: '64M'
})
```

#### Connect Cache Backend

```
// Cache remote backend locally
const cacheBackend = await client.files.backends.connectCache({
  name: 'cached-gdrive',
  remote: 'gdrive-backend:',
  info_age: '6h',
  chunk_total_size: '10G'
})
```

#### Connect Crypt Backend

```
// Encrypt files on remote backend
const cryptBackend = await client.files.backends.connectCrypt({
  name: 'encrypted-s3',
  remote: 's3-backend:secure-bucket',
  password: 'your-strong-password-256-bit',
  password2: 'your-second-password-for-filename-encryption'
})
```

#### Connect Compress Backend

```
// Compress files on remote backend
const compressBackend = await client.files.backends.connectCompress({
  name: 'compressed-storage',
  remote: 's3-backend:bucket',
  mode: 'gzip'
})
```

#### Connect Hasher Backend

```
// Add checksums to remote backend
const hasherBackend = await client.files.backends.connectHasher({
  name: 'hashed-gdrive',
  remote: 'gdrive-backend:',
  hashes: 'sha1,md5'
})
```

#### Connect Cloudinary Backend

```
// Connect to Cloudinary
const cloudinaryBackend = await client.files.backends.connectCloudinary({
  name: 'cloudinary-media',
  cloud_name: 'your-cloud-name',
  api_key: 'your-api-key',
  api_secret: 'your-api-secret'
})
```

#### Connect Google Photos Backend

```
// Connect to Google Photos
const photosBackend = await client.files.backends.connectGooglePhotos({
  name: 'google-photos',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: '{"access_token":"...","refresh_token":"..."}',
  read_only: true
})
```

#### Connect ImageKit Backend

```
// Connect to ImageKit
const imagekitBackend = await client.files.backends.connectImagekit({
  name: 'imagekit-cdn',
  public_key: 'your-public-key',
  private_key: 'your-private-key',
  endpoint: 'https://ik.imagekit.io/your_endpoint'
})
```

#### Connect iCloud Drive Backend

```
// Connect to iCloud Drive
const icloudBackend = await client.files.backends.connectIclouddrive({
  name: 'icloud-drive',
  apple_id: 'user@icloud.com',
  password: 'app-specific-password'
})
```

#### Connect ProtonDrive Backend

```
// Connect to ProtonDrive
const protonBackend = await client.files.backends.connectProtondrive({
  name: 'proton-drive',
  username: 'user@protonmail.com',
  password: 'your-password',
  '2fa': '123456'
})
```

#### Connect Koofr Backend

```
// Connect to Koofr
const koofrBackend = await client.files.backends.connectKoofr({
  name: 'koofr-storage',
  user: 'user@example.com',
  password: 'your-password'
})
```

#### Connect Seafile Backend

```
// Connect to Seafile
const seafileBackend = await client.files.backends.connectSeafile({
  name: 'seafile-library',
  url: 'https://cloud.example.com',
  user: 'user@example.com',
  password: 'your-password',
  library: 'my-library-id'
})
```

#### Connect put.io Backend

```
// Connect to put.io
const putioBackend = await client.files.backends.connectPutio({
  name: 'putio-files',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: '{"access_token":"..."}'
})
```

#### Connect HDFS Backend

```
// Connect to Hadoop HDFS
const hdfsBackend = await client.files.backends.connectHdfs({
  name: 'hadoop-hdfs',
  namenode: 'namenode.example.com',
  port: 9870,
  service_account_name: 'hdfs-user'
})
```

#### Connect HiDrive Backend

```
// Connect to HiDrive
const hidriveBackend = await client.files.backends.connectHidrive({
  name: 'hidrive-storage',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: '{"access_token":"...","refresh_token":"..."}'
})
```

#### Connect Yandex Disk Backend

```
// Connect to Yandex Disk
const yandexBackend = await client.files.backends.connectYandex({
  name: 'yandex-disk',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: '{"access_token":"...","refresh_token":"..."}'
})
```

#### Connect Zoho WorkDrive Backend

```
// Connect to Zoho WorkDrive
const zohoBackend = await client.files.backends.connectZoho({
  name: 'zoho-workdrive',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: '{"access_token":"...","refresh_token":"..."}',
  region: 'us'
})
```

#### Connect 1Fichier Backend

```
// Connect to 1Fichier
const fichierBackend = await client.files.backends.connectFichier({
  name: 'fichier-storage',
  api_key: 'your-api-key'
})
```

#### Connect Filefabric Backend

```
// Connect to Enterprise File Fabric
const filefabricBackend = await client.files.backends.connectFilefabric({
  name: 'enterprise-filefabric',
  url: 'https://storagemadeeasy.com',
  user: 'user@example.com',
  password: 'your-password'
})
```

#### Connect Files.com Backend

```
// Connect to Files.com
const filescomBackend = await client.files.backends.connectFilescom({
  name: 'files-com',
  api_key: 'your-api-key'
})
```

#### Connect Gofile Backend

```
// Connect to Gofile
const gofileBackend = await client.files.backends.connectGofile({
  name: 'gofile-storage',
  api_key: 'your-api-key'
})
```

#### Connect Internet Archive Backend

```
// Connect to Internet Archive
const iaBackend = await client.files.backends.connectInternetarchive({
  name: 'internet-archive',
  access_key_id: 'your-access-key',
  secret_access_key: 'your-secret-key'
})
```

#### Connect Jottacloud Backend

```
// Connect to Jottacloud
const jottaBackend = await client.files.backends.connectJottacloud({
  name: 'jottacloud',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: '{"access_token":"...","refresh_token":"..."}'
})
```

#### Connect Linkbox Backend

```
// Connect to Linkbox
const linkboxBackend = await client.files.backends.connectLinkbox({
  name: 'linkbox-storage',
  token: 'your-api-token'
})
```

#### Connect mail.ru Cloud Backend

```
// Connect to mail.ru Cloud
const mailruBackend = await client.files.backends.connectMailru({
  name: 'mailru-cloud',
  user: 'user@list.ru',
  pass: 'your-password',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret'
})
```

#### Connect Memory Backend

```
// Create in-memory storage backend
const memoryBackend = await client.files.backends.connectMemory({
  name: 'temp-storage'
})
```

#### Connect NetStorage Backend

```
// Connect to Akamai NetStorage
const netstorageBackend = await client.files.backends.connectNetstorage({
  name: 'akamai-storage',
  host: 'example-nsu.akamaihd.net',
  account: 'your-account',
  key: 'your-key'
})
```

#### Connect OpenDrive Backend

```
// Connect to OpenDrive
const opendriveBackend = await client.files.backends.connectOpendrive({
  name: 'opendrive',
  user: 'user@example.com',
  password: 'your-password'
})
```

#### Connect Oracle Object Storage Backend

```
// Connect to Oracle Cloud Object Storage
const oracleBackend = await client.files.backends.connectOracleobjectstorage({
  name: 'oracle-oci',
  compartment: 'ocid1.compartment.oc1..aaaa',
  namespace: 'your-namespace',
  region: 'us-ashburn-1',
  tenancy: 'ocid1.tenancy.oc1..aaaa',
  user: 'ocid1.user.oc1..aaaa',
  key_file: '/path/to/key.pem',
  passphrase: 'key-passphrase'
})
```

#### Connect PikPak Backend

```
// Connect to PikPak
const pikpakBackend = await client.files.backends.connectPikpak({
  name: 'pikpak-cloud',
  user: 'user@example.com',
  pass: 'your-password'
})
```

#### Connect Pixeldrain Backend

```
// Connect to Pixeldrain
const pixeldrainBackend = await client.files.backends.connectPixeldrain({
  name: 'pixeldrain',
  api_key: 'your-api-key'
})
```

#### Connect Premiumize.me Backend

```
// Connect to Premiumize.me
const premiumizeBackend = await client.files.backends.connectPremiumizeme({
  name: 'premiumize',
  api_key: 'your-api-key'
})
```

#### Connect QingStor Backend

```
// Connect to QingStor
const qingstorBackend = await client.files.backends.connectQingstor({
  name: 'qingstor',
  access_key_id: 'your-access-key',
  secret_access_key: 'your-secret-key',
  endpoint: 'https://pek3a.qingstor.com',
  zone: 'pek3a'
})
```

#### Connect Quatrix Backend

```
// Connect to Quatrix
const quatrixBackend = await client.files.backends.connectQuatrix({
  name: 'quatrix-storage',
  api_token: 'your-api-token',
  url: 'https://your-account.quatrix.com'
})
```

#### Connect Sia Backend

```
// Connect to Sia decentralized storage
const siaBackend = await client.files.backends.connectSia({
  name: 'sia-storage',
  api_url: 'http://localhost:9980',
  api_password: 'your-api-password'
})
```

#### Connect SMB/CIFS Backend

```
// Connect to SMB/CIFS share
const smbBackend = await client.files.backends.connectSmb({
  name: 'network-share',
  host: 'fileserver.local',
  user: 'domain\\username',
  pass: 'your-password',
  domain: 'WORKGROUP'
})
```

#### Connect SugarSync Backend

```
// Connect to SugarSync
const sugarsyncBackend = await client.files.backends.connectSugarsync({
  name: 'sugarsync',
  access_key_id: 'your-access-key',
  private_access_key: 'your-private-key',
  user: 'user@example.com',
  password: 'your-password'
})
```

#### Connect Uloz.to Backend

```
// Connect to Uloz.to
const uloztoBackend = await client.files.backends.connectUlozto({
  name: 'ulozto',
  user: 'your-username',
  password: 'your-password'
})
```

#### Connect Uptobox Backend

```
// Connect to Uptobox
const uptoboxBackend = await client.files.backends.connectUptobox({
  name: 'uptobox',
  api_key: 'your-api-key'
})
```

#### Get Backend Details

```
// Get detailed info about a specific backend
const details = await client.files.backends.getDetails({ id: 'backend_s3_001' })
```

Expected response for backend details:

```
{
  "id": "backend_s3_001",
  "type": "s3",
  "name": "My S3 Bucket",
  "status": "connected",
  "config": {
    "provider": "AWS",
    "region": "us-east-1",
    "endpoint": "https://s3.amazonaws.com"
  },
  "stats": {
    "total_files": 15420,
    "total_size": 53687091200,
    "last_sync": "2025-01-15T14:00:00Z"
  },
  "created_at": "2025-01-10T09:00:00Z",
  "updated_at": "2025-01-15T14:00:00Z"
}
```

#### Update Backend Credentials

```
// Rotate credentials for existing backend
const updated = await client.files.backends.update('backend_s3_001', {
  access_key_id: 'AKIAIOSFODNN7NEWKEY',
  secret_access_key: 'wJalrXUtnFEMI/K7MDENG/newSecretKey'
})
```

Expected response for credential update:

```
{
  "id": "backend_s3_001",
  "type": "s3",
  "name": "My S3 Bucket",
  "status": "connected",
  "credentials_updated": true,
  "updated_at": "2025-01-15T15:00:00Z"
}
```

#### Test Backend Connection

```
// Verify backend connection is working
const testResult = await client.files.backends.testConnection({ id: 'backend_s3_001' })
```

Expected response for connection test:

```
{
  "id": "backend_s3_001",
  "status": "ok",
  "latency_ms": 45,
  "storage_class": "STANDARD",
  "bucket_exists": true,
  "readable": true,
  "writable": true
}
```

#### Disconnect Backend

```
// Disconnect and remove backend
await client.files.backends.disconnect({ id: 'backend_s3_001' })
```

---

### 7. Remote File Access

#### Access Files via Git Repository

```
// Access file from GitHub repository
const readme = await client.files.get('README.md', {
  type: 'git',
  url: 'https://github.com/user/repo.git',
  ref: 'main'
})

// Access from private Git repo with authentication
const privateFile = await client.files.get('src/index.ts', {
  type: 'git',
  url: 'https://github.com/org/private-repo.git',
  ref: 'develop',
  pass: 'ghp_xxxxxxxxxxxx'
})

// Access from GitLab
const gitlabFile = await client.files.get('docs/guide.md', {
  type: 'git',
  url: 'https://gitlab.com/group/project.git',
  ref: 'v2.0.0'
})
```

#### Access Files via S3

```
// Access file from S3 bucket
const s3File = await client.files.get('path/to/file.txt', {
  type: 's3',
  server: 's3.amazonaws.com',
  s3_bucket: 'my-bucket',
  s3_region: 'us-east-1'
})

// Access from MinIO with credentials
const minioFile = await client.files.get('data/report.csv', {
  type: 's3',
  server: 'minio.example.com',
  s3_bucket: 'analytics',
  s3_region: 'us-east-1',
  user: 'minioadmin',
  pass: 'minioadmin'
})
```

#### Access Files via SSH/SFTP

```
// Read file from SSH server
const sshFile = await client.files.get('remote/path/file.txt', {
  type: 'ssh',
  server: 'ssh.example.com',
  user: 'deploy',
  pass: 'ssh-password'
})

// Read file using SSH key
const sshKeyFile = await client.files.get('config/app.conf', {
  type: 'ssh',
  server: 'production.example.com',
  user: 'admin',
  key: '-----BEGIN OPENSSH PRIVATE KEY-----\n...',
  passphrase: 'key-passphrase'
})

// Upload file to SSH server
await client.files.put('remote/path/upload.txt', {
  type: 'ssh',
  server: 'ssh.example.com',
  user: 'deploy',
  pass: 'ssh-password'
})
```

#### Access Files via FTP

```
// Access file from FTP server
const ftpFile = await client.files.get('pub/data/file.csv', {
  type: 'ftp',
  server: 'ftp.example.com',
  user: 'anonymous',
  pass: 'user@example.com'
})

// Access with FTPS
const ftpsFile = await client.files.get('secure/data.zip', {
  type: 'ftp',
  server: 'ftps.example.com',
  user: 'ftpuser',
  pass: 'ftppass',
  ftp_secure: true,
  ftp_passive: true
})
```

#### Access Files via WebDAV

```
// Access file from WebDAV server
const webdavFile = await client.files.get('Documents/report.pdf', {
  type: 'webdav',
  server: 'https://cloud.example.com',
  user: 'username',
  pass: 'password',
  webdav_path: '/remote.php/dav/files/user/'
})

// Access from Nextcloud
const nextcloudFile = await client.files.get('Photos/image.jpg', {
  type: 'webdav',
  server: 'https://nextcloud.example.com',
  user: 'ncuser',
  pass: 'ncpassword',
  webdav_path: '/remote.php/dav/files/ncuser/'
})
```

---

### 8. Image Processing

#### Process and Resize Images

```
// Generate thumbnail
const thumbnail = await client.files.images.process('images/photo.jpg', 'thumbnail', {
  size: 'thumb'
})

// Resize to specific dimensions
const resized = await client.files.images.process('uploads/original.png', 'thumbnail', {
  width: 800,
  height: 600,
  resize: 'fill'
})

// Convert format and adjust quality
const webp = await client.files.images.process('photos/landscape.jpg', 'thumbnail', {
  format: 'webp',
  quality: 80
})

// Apply effects
const processed = await client.files.images.process('images/source.jpg', 'thumbnail', {
  size: 'large',
  blur: 2.5,
  grayscale: 'true'
})

// Process with background color (for transparent PNGs)
const withBg = await client.files.images.process('logos/logo-transparent.png', 'thumbnail', {
  format: 'jpg',
  bg: 'ffffff'
})
```

Expected response for image processing returns the processed image binary directly with appropriate Content-Type header.

---

### 9. Health Check

```
// Check service health
const health = await client.files.health.check()
```

Expected response for health check:

```
{
  "status": "ok",
  "service": "hoody-files",
  "version": "1.0.0",
  "build_time": "2025-01-10T08:00:00Z",
  "start_time": "2025-01-15T00:00:00Z",
  "uptime": 86400,
  "resources": {
    "memory_used": 134217728,
    "memory_total": 536870912,
    "cpu_percent": 12.5
  },
  "caller": {
    "ip": "192.168.1.100",
    "user_agent": "HoodySDK/1.0"
  }
}
```

---

### 10. Journal (File Mutation Tracking)

#### Query Journal Entries

```
// Query all journal entries
const entries = await client.files.journal.query()

// Query with filters
const filtered = await client.files.journal.query({
  path: 'data/uploads/',
  op: 'create',
  since: '2025-01-15T00:00:00Z',
  limit: 50
})

// Paginate through journal
const page2 = await client.files.journal.query({
  after_id: 100,
  limit: 50
})

// Filter by operation type
const deletes = await client.files.journal.query({
  op: 'delete',
  limit: 20
})
```

Expected response for journal query:

```
{
  "entries": [
    {
      "id": 42,
      "path": "data/uploads/report.pdf",
      "op": "create",
      "size": 1048576,
      "timestamp": "2025-01-15T10:30:00Z",
      "user": "app-user"
    },
    {
      "id": 43,
      "path": "data/uploads/report.pdf",
      "op": "modify",
      "size": 1048576,
      "old_size": 1048000,
      "timestamp": "2025-01-15T10:35:00Z",
      "user": "app-user"
    }
  ],
  "total": 2,
  "has_more": false,
  "last_id": 43
}
```

#### Flush Journal to Disk

```
// Force flush all pending journal entries
const flushResult = await client.files.journal.flush()
```

Expected response for journal flush:

```
{
  "flushed": true,
  "entries_written": 15,
  "duration_ms": 42
}
```

#### Get Journal Statistics

```
// Get journal storage statistics
const stats = await client.files.journal.getStats()
```

Expected response for journal stats:

```
{
  "total_entries": 15420,
  "entries_today": 142,
  "storage_used_bytes": 5242880,
  "blob_storage_bytes": 1048576,
  "writer_healthy": true,
  "last_prune": "2025-01-14T00:00:00Z",
  "prune_threshold_days": 30
}
```

---

### 11. Mounts (FUSE Filesystem Mounts)

#### List All Mounts

```
// List all active mounts
const mounts = await client.files.mounts.list()

// List mounts with label filter
const filtered = await client.files.mounts.list({ label: 'production' })
```

Expected response for mount listing:

```
{
  "mounts": [
    {
      "id": "mount_001",
      "backend_id": "backend_s3_001",
      "mount_point": "/mnt/s3-data",
      "status": "mounted",
      "label": "production",
      "created_at": "2025-01-10T09:00:00Z",
      "vfs_config": {
        "cache_mode": "full",
        "buffer_size": "64M"
      }
    }
  ],
  "total": 1
}
```

#### Create Persistent FUSE Mount

```
// Create mount for S3 backend
const mount = await client.files.mounts.create({
  backend_id: 'backend_s3_001',
  mount_point: '/mnt/s3-data',
  label: 'production',
  vfs_config: {
    cache_mode: 'full',
    cache_size: '10G',
    buffer_size: '64M',
    dir_cache_time: '5m',
    read_ahead: '128M'
  }
})

// Create mount for Google Drive
const gdriveMount = await client.files.mounts.create({
  backend_id: 'backend_gdrive_002',
  mount_point: '/mnt/google-drive',
  label: 'team-files',
  vfs_config: {
    cache_mode: 'writes',
    cache_size: '5G'
  }
})
```

Expected response for mount creation:

```
{
  "id": "mount_002",
  "backend_id": "backend_s3_001",
  "mount_point": "/mnt/s3-data",
  "status": "mounting",
  "label": "production",
  "created_at": "2025-01-15T15:00:00Z",
  "vfs_config": {
    "cache_mode": "full",
    "cache_size": "10G",
    "buffer_size": "64M",
    "dir_cache_time": "5m",
    "read_ahead": "128M"
  }
}
```

#### Get Mount Details

```
// Get detailed info about a specific mount
const details = await client.files.mounts.getDetails({ id: 'mount_001' })
```

Expected response for mount details:

```
{
  "id": "mount_001",
  "backend_id": "backend_s3_001",
  "backend_type": "s3",
  "mount_point": "/mnt/s3-data",
  "status": "mounted",
  "label": "production",
  "created_at": "2025-01-10T09:00:00Z",
  "mounted_at": "2025-01-10T09:00:05Z",
  "stats": {
    "files_cached": 1520,
    "cache_used": 2147483648,
    "operations_total": 45230,
    "last_access": "2025-01-15T14:55:00Z"
  },
  "vfs_config": {
    "cache_mode": "full",
    "cache_size": "10G",
    "buffer_size": "64M"
  }
}
```

#### Update Mount Configuration

```
// Update VFS settings for existing mount
const updated = await client.files.mounts.update('mount_001', {
  vfs_config: {
    cache_mode: 'full',
    cache_size: '20G',
    buffer_size: '128M',
    dir_cache_time: '10m'
  }
})
```

Expected response for mount update:

```
{
  "id": "mount_001",
  "backend_id": "backend_s3_001",
  "mount_point": "/mnt/s3-data",
  "status": "reloading",
  "vfs_config": {
    "cache_mode": "full",
    "cache_size": "20G",
    "buffer_size": "128M",
    "dir_cache_time": "10m"
  },
  "updated_at": "2025-01-15T16:00:00Z"
}
```

#### Unmount Filesystem

```
// Remove mount and disconnect FUSE filesystem
await client.files.mounts.unmount({ id: 'mount_001' })
```

---

### 12. System Information

#### Get API Version

```
// Get current API version and server info
const version = await client.files.system.getApiVersion()
```

Expected response for version:

```
{
  "version": "1.42.0",
  "decomposed_version": [1, 42, 0],
  "is_release": true,
  "arch": "amd64",
  "go_version": "go1.22.0",
  "os": "linux",
  "linking": "static"
}
```

---

### 13. WebDAV Operations

#### Get Supported Methods

```
// Get WebDAV capabilities for a path
await client.files.webdav.getOptions({ path: 'path/to/resource' })
```

#### Copy Resource

```
// Copy file or directory via WebDAV
const result = await client.files.webdav.copyResource('source/file.txt', '/destination/file.txt')

// Copy with depth control
const dirCopy = await client.files.webdav.copyResource('source/dir/', '/destination/dir/', 'infinity')
```

#### Move or Rename Resource

```
// Move/rename file via WebDAV
const result = await client.files.webdav.moveResource('old/path.txt', '/new/path.txt')
```

#### Lock Resource

```
// Lock file for exclusive editing
const lockResult = await client.files.webdav.lockResource('documents/editing.docx', 'infinity')
```

Expected response for lock:

```
{
  "lock_token": "urn:uuid:a515cfa4-5da4-22e1-f0ce-023456789abc",
  "timeout": "Second-3600",
  "lockscope": "exclusive",
  "locktype": "write"
}
```

#### Unlock Resource

```
// Unlock previously locked file
await client.files.webdav.unlockResource(
  'documents/editing.docx',
  'urn:uuid:a515cfa4-5da4-22e1-f0ce-023456789abc'
)
```

#### Get WebDAV Properties

```
// Get WebDAV properties for resource
await client.files.webdav.propfindResource('path/to/resource', '1')

// Get properties recursively
await client.files.webdav.propfindResource('directory/', 'infinity')
```

#### Update WebDAV Properties

```
// Update WebDAV properties
await client.files.webdav.proppatchResource({ path: 'path/to/resource' })
```

---

### 14. Directory Operations

#### Create Directory (MKCOL)

```
// Create new directory
await client.files.directories.create({ path: 'new/directory/path' })
```

---

### 15. Authentication Operations

#### Check Authentication Status

```
// Check if current authentication is valid
const authStatus = await client.files.authentication.checkAuth({ path: 'path/to/resource' })
```

Expected response for auth check:

```
{
  "authenticated": true,
  "user": "app-user",
  "expires_at": "2025-01-15T23:59:59Z",
  "permissions": ["read", "write", "delete"]
}
```

#### Logout (Clear Authentication)

```
// Clear current authentication session
await client.files.authentication.logout({ path: 'path/to/resource' })
```

---

## Advanced Operations

### 16. Multi-Backend File Migration

Migrate files from one cloud provider to another with verification:

```
async function migrateFiles(
  sourceBackendId: string,
  destBackendId: string,
  sourcePath: string,
  destPath: string
) {
  // Step 1: Test source connection
  const sourceTest = await client.files.backends.testConnection(sourceBackendId)
  if (sourceTest.status !== 'ok') {
    throw new Error(`Source backend ${sourceBackendId} not ready: ${sourceTest.status}`)
  }

  // Step 2: Test destination connection
  const destTest = await client.files.backends.testConnection(destBackendId)
  if (destTest.status !== 'ok') {
    throw new Error(`Destination backend ${destBackendId} not ready: ${destTest.status}`)
  }

  // Step 3: List source files
  const sourceFiles = await client.files.glob(sourcePath, {
    pattern: '**/*',
    max_results: 10000
  })

  console.log(`Found ${sourceFiles.total} files to migrate`)

  // Step 4: Copy files to destination
  const copyResult = await client.files.copy(
    `${sourcePath}`,
    destPath,
    {
      overwrite: 'true'
    }
  )

  // Step 5: Verify by listing destination
  const destFiles = await client.files.glob(destPath, {
    pattern: '**/*',
    max_results: 10000
  })

  if (destFiles.total !== sourceFiles.total) {
    console.warn(
      `Migration mismatch: source=${sourceFiles.total}, dest=${destFiles.total}`
    )
  }

  // Step 6: Compare file stats for verification
  const sourceStats = await client.files.stat(sourcePath)
  const destStats = await client.files.stat(destPath)

  return {
    source_files: sourceFiles.total,
    dest_files: destFiles.total,
    source_size: sourceStats.size,
    dest_size: destStats.size,
    migration_complete: sourceFiles.total === destFiles.total
  }
}

// Usage
const result = await migrateFiles(
  'backend_gdrive_001',
  'backend_s3_002',
  'documents/projects/',
  'archive/projects/'
)
```

### 17. Automated Backup Workflow

Create timestamped backups with compression and verification:

```
async function createBackup(sourcePath: string, backupDir: string) {
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
  const backupName = `backup-${timestamp}`

  // Step 1: Ensure backup directory exists
  await client.files.operate(backupDir, { mkdir: 'true' })

  // Step 2: Copy source to backup location
  const backupPath = `${backupDir}/${backupName}`
  await client.files.copy(sourcePath, backupPath, { overwrite: 'true' })

  // Step 3: Create ZIP archive of backup
  const zipResult = await client.files.archives.downloadAsZip(backupPath, 'download')

  // Step 4: Get backup statistics
  const stats = await client.files.stat(backupPath)
  const globResult = await client.files.glob(backupPath, {
    pattern: '**/*',
    max_results: 1000
  })

  // Step 5: Verify backup integrity
  const listing = await client.files.listDirectory(backupPath, { json: 'true' })

  return {
    backup_path: backupPath,
    backup_name: backupName,
    total_files: globResult.total,
    total_size: stats.size,
    created_at: new Date().toISOString(),
    verified: listing.entries && listing.entries.length > 0
  }
}

// Usage
const backup = await createBackup('app/data/', 'backups/')
```

### 18. Bulk File Processing Pipeline

Process files with grep/glob patterns and apply operations:

```
async function processFilesWithPattern(
  searchPath: string,
  globPattern: string,
  grepPattern: string,
  outputPath: string
) {
  // Step 1: Find matching files
  const matchedFiles = await client.files.glob(searchPath, {
    pattern: globPattern,
    max_results: 5000
  })

  console.log(`Found ${matchedFiles.total} files matching pattern`)

  // Step 2: Search file contents
  const grepResults = await client.files.grep(searchPath, {
    pattern: grepPattern,
    glob: globPattern,
    max_matches: 10000,
    context: 1
  })

  console.log(`Found ${grepResults.total_matches} matches across ${grepResults.files_searched} files`)

  // Step 3: Create output directory
  await client.files.operate(outputPath, { mkdir: 'true' })

  // Step 4: Copy matched files to output
  const uniquePaths = new Set(
    grepResults.matches.map((m: { path: string }) => m.path)
  )

  for (const filePath of uniquePaths) {
    const fileName = filePath.split('/').pop()
    const destPath = `${outputPath}/${fileName}`
    await client.files.copy(filePath, destPath, { overwrite: 'true' })
  }

  return {
    files_searched: grepResults.files_searched,
    total_matches: grepResults.total_matches,
    unique_files: uniquePaths.size,
    output_path: outputPath
  }
}

// Usage: Find all TypeScript files containing 'TODO' comments
const results = await processFilesWithPattern(
  'src/',
  '**/*.ts',
  'TODO|FIXME|HACK',
  'review/todo-items/'
)
```

### 19. Multi-Mount Orchestration

Set up and manage multiple mounts for unified access:

```
async function setupUnifiedMounts(backends: Array<{
  id: string
  mount_point: string
  label: string
}>) {
  const results = []

  for (const backend of backends) {
    // Step 1: Test connection
    const test = await client.files.backends.testConnection(backend.id)
    if (test.status !== 'ok') {
      console.error(`Backend ${backend.id} failed connection test`)
      results.push({ id: backend.id, status: 'failed', error: test.status })
      continue
    }

    // Step 2: Check for existing mounts
    const existingMounts = await client.files.mounts.list({ label: backend.label })
    const existing = existingMounts.mounts.find(
      (m: { backend_id: string }) => m.backend_id === backend.id
    )

    if (existing) {
      console.log(`Mount already exists for ${backend.id}: ${existing.id}`)
      results.push({ id: backend.id, status: 'exists', mount_id: existing.id })
      continue
    }

    // Step 3: Create mount
    const mount = await client.files.mounts.create({
      backend_id: backend.id,
      mount_point: backend.mount_point,
      label: backend.label,
      vfs_config: {
        cache_mode: 'full',
        cache_size: '5G',
        buffer_size: '64M'
      }
    })

    results.push({ id: backend.id, status: 'created', mount_id: mount.id })
  }

  return results
}

// Usage
const mounts = await setupUnifiedMounts([
  { id: 'backend_s3_001', mount_point: '/mnt/s3', label: 'cloud-storage' },
  { id: 'backend_gdrive_002', mount_point: '/mnt/gdrive', label: 'cloud-storage' },
  { id: 'backend_dropbox_003', mount_point: '/mnt/dropbox', label: 'cloud-storage' }
])
```

### 20. Journal-Based Change Tracking

Monitor and react to file changes via the journal:

```
async function watchForChanges(
  pathPrefix: string,
  operations: string[],
  callback: (entry: { id: number; path: string; op: string }) => Promise<void>
) {
  let lastId = 0

  // Get initial position
  const initial = await client.files.journal.query({
    path: pathPrefix,
    limit: 1
  })
  if (initial.entries && initial.entries.length > 0) {
    lastId = initial.entries[0].id
  }

  // Poll for new entries
  const poll = async () => {
    const newEntries = await client.files.journal.query({
      path: pathPrefix,
      after_id: lastId,
      limit: 100
    })

    for (const entry of newEntries.entries) {
      if (operations.includes(entry.op)) {
        await callback(entry)
      }
      lastId = entry.id
    }

    return newEntries.total
  }

  return { poll, getLastId: () => lastId }
}

// Usage
const watcher = await watchForChanges(
  'data/uploads/',
  ['create', 'modify'],
  async (entry) => {
    console.log(`File changed: ${entry.path} (${entry.op})`)
    // Trigger downstream processing
    await client.files.copy(entry.path, `processed/${entry.path}`)
  }
)

// In your application loop:
// const count = await watcher.poll()
```

### 21. Error Recovery for Backend Operations

Handle connection failures gracefully:

```
async function resilientBackendOperation(
  backendId: string,
  maxRetries: number = 3
) {
  let attempt = 0

  while (attempt < maxRetries) {
    try {
      // Test connection first
      const test = await client.files.backends.testConnection(backendId)

      if (test.status === 'ok') {
        // Proceed with operation
        return { success: true, backend: backendId, attempt: attempt + 1 }
      }

      // Connection failed - attempt credential refresh
      if (attempt < maxRetries - 1) {
        console.log(`Connection test failed, retrying (${attempt + 1}/${maxRetries})`)

        // Wait before retry
        await new Promise(resolve => setTimeout(resolve, 1000 * (attempt + 1)))
      }
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error)

      if (attempt === maxRetries - 1) {
        throw new Error(`Backend ${backendId} unreachable after ${maxRetries} attempts`)
      }
    }

    attempt++
  }

  return { success: false, backend: backendId, attempt }
}

// Usage
try {
  const result = await resilientBackendOperation('backend_s3_001')
  if (result.success) {
    console.log(`Backend ready after ${result.attempt} attempts`)
  }
} catch (error) {
  console.error('Backend operation failed:', error)
  // Trigger alerting or fallback
}
```

### 22. Archive Extraction Pipeline

Extract and organize archived files with progress tracking:

```
async function extractAndOrganize(
  archivePath: string,
  extractBase: string,
  organizationRules: Array<{
    pattern: string
    destination: string
  }>
) {
  // Step 1: Preview archive contents
  const preview = await client.files.archives.preview(archivePath)
  console.log(`Archive contains ${preview.total_entries} entries`)

  // Step 2: Extract to temporary location
  const tempDir = `${extractBase}/.temp-extract`
  await client.files.operate(tempDir, { mkdir: 'true' })

  const extraction = await client.files.archives.extract(archivePath, 'extract', tempDir)

  // Step 3: Monitor extraction progress
  let status = 'in_progress'
  while (status === 'in_progress') {
    const active = await client.files.archives.listGlobal()
    const current = active.extractions.find(
      (e: { extraction_id: string }) => e.extraction_id === extraction.extraction_id
    )

    if (!current || current.status === 'completed') {
      status = 'completed'
    } else if (current.status === 'failed') {
      throw new Error(`Extraction failed: ${current.error}`)
    } else {
      await new Promise(resolve => setTimeout(resolve, 1000))
    }
  }

  // Step 4: Organize files by rules
  const organized = []
  for (const rule of organizationRules) {
    const matched = await client.files.glob(tempDir, {
      pattern: rule.pattern,
      max_results: 5000
    })

    await client.files.operate(rule.destination, { mkdir: 'true' })

    for (const file of matched.matches) {
      const fileName = file.path.split('/').pop()
      await client.files.copy(file.path, `${rule.destination}/${fileName}`, {
        overwrite: 'true'
      })
      organized.push({ source: file.path, destination: `${rule.destination}/${fileName}` })
    }
  }

  return {
    archive: archivePath,
    total_extracted: preview.total_entries,
    organized_files: organized.length,
    extraction_id: extraction.extraction_id
  }
}

// Usage
const result = await extractAndOrganize('uploads/project-bundle.tar.gz', 'workspace/', [
  { pattern: '**/*.ts', destination: 'workspace/typescript/' },
  { pattern: '**/*.{jpg,png,gif}', destination: 'workspace/images/' },
  { pattern: '**/*.{json,yaml}', destination: 'workspace/config/' }
])
```

### 23. Bulk Backend Credential Rotation

Rotate credentials for multiple backends systematically:

```
async function rotateBackendCredentials(
  credentials: Array<{
    id: string
    new_credentials: Record<string, string>
  }>
) {
  const results = []

  for (const { id, new_credentials } of credentials) {
    try {
      // Step 1: Get current backend info
      const details = await client.files.backends.getDetails(id)

      // Step 2: Update credentials
      const updated = await client.files.backends.update(id, new_credentials)

      // Step 3: Verify connection with new credentials
      const test = await client.files.backends.testConnection(id)

      // Step 4: Update associated mounts if connection works
      if (test.status === 'ok') {
        const mounts = await client.files.mounts.list()
        const backendMounts = mounts.mounts.filter(
          (m: { backend_id: string }) => m.backend_id === id
        )

        for (const mount of backendMounts) {
          // Trigger mount refresh
          await client.files.mounts.update(mount.id, {
            vfs_config: mount.vfs_config
          })
        }
      }

      results.push({
        id,
        status: test.status,
        credentials_updated: true,
        mounts_refreshed: test.status === 'ok'
      })
    } catch (error) {
      results.push({
        id,
        status: 'error',
        error: error instanceof Error ? error.message : 'Unknown error'
      })
    }
  }

  return results
}

// Usage
const rotation = await rotateBackendCredentials([
  {
    id: 'backend_s3_001',
    new_credentials: {
      access_key_id: 'AKIAIOSFODNN7NEWKEY',
      secret_access_key: 'newSecretKey123'
    }
  },
  {
    id: 'backend_gdrive_002',
    new_credentials: {
      token: '{"access_token":"new_token","refresh_token":"new_refresh"}'
    }
  }
])
```

### 24. Full Container File System Setup

Initialize a container with standard directory structure and mounts:

```
async function initializeContainerFilesystem(backends: Array<{
  id: string
  type: string
  mount_point: string
}>) {
  // Step 1: Create standard directories
  const directories = [
    'app/data',
    'app/config',
    'app/logs',
    'app/cache',
    'app/temp',
    'app/backups',
    'app/uploads',
    'app/processed'
  ]

  for (const dir of directories) {
    await client.files.operate(dir, { mkdir: 'true' })
  }

  // Step 2: Set directory permissions
  await client.files.chmod({ path: 'app/data', chmod: '755' })
  await client.files.chmod({ path: 'app/config', chmod: '700' })
  await client.files.chmod({ path: 'app/logs', chmod: '755' })
  await client.files.chmod({ path: 'app/temp', chmod: '1777' })

  // Step 3: Set up cloud storage mounts
  const mountResults = []
  for (const backend of backends) {
    const test = await client.files.backends.testConnection(backend.id)

    if (test.status === 'ok') {
      const mount = await client.files.mounts.create({
        backend_id: backend.id,
        mount_point: backend.mount_point,
        label: `${backend.type}-storage`,
        vfs_config: {
          cache_mode: 'full',
          cache_size: '5G',
          buffer_size: '64M'
        }
      })
      mountResults.push({ ...backend, mount_id: mount.id, status: 'mounted' })
    } else {
      mountResults.push({ ...backend, mount_id: null, status: 'connection_failed' })
    }
  }

  // Step 4: Verify directory structure
  const structure = await client.files.listDirectory('app', { json: 'true' })

  // Step 5: Get system info
  const version = await client.files.system.getApiVersion()
  const health = await client.files.health.check()

  return {
    directories_created: directories.length,
    mounts_configured: mountResults.length,
    mounts_active: mountResults.filter(m => m.status === 'mounted').length,
    structure: structure.entries?.map((e: { name: string }) => e.name) || [],
    system: {
      version: version.version,
      health: health.status
    }
  }
}

// Usage
const init = await initializeContainerFilesystem([
  { id: 'backend_s3_001', type: 's3', mount_point: '/mnt/cloud/s3' },
  { id: 'backend_gdrive_002', type: 'drive', mount_point: '/mnt/cloud/gdrive' },
  { id: 'backend_dropbox_003', type: 'dropbox', mount_point: '/mnt/cloud/dropbox' }
])
```

### 25. Search and Audit Pipeline

Comprehensive file audit combining multiple search methods:

```
async function auditFilesystem(
  searchPath: string,
  auditConfig: {
    sensitivePatterns: string[]
    largeFileThreshold: number
    staleDays: number
  }
) {
  const report: {
    sensitive_files: Array<{ path: string; matches: string[] }>
    large_files: Array<{ path: string; size: number }>
    stale_files: Array<{ path: string; modTime: string }>
    total_files: number
    total_size: number
    directories: number
  } = {
    sensitive_files: [],
    large_files: [],
    stale_files: [],
    total_files: 0,
    total_size: 0,
    directories: 0
  }

  // Step 1: Get overall file listing
  const allFiles = await client.files.glob(searchPath, {
    pattern: '**/*',
    max_results: 50000
  })

  report.total_files = allFiles.matches.filter(
    (f: { type: string }) => f.type === 'file'
  ).length
  report.directories = allFiles.matches.filter(
    (f: { type: string }) => f.type === 'dir'
  ).length

  // Step 2: Search for sensitive content
  for (const pattern of auditConfig.sensitivePatterns) {
    const matches = await client.files.grep(searchPath, {
      pattern,
      max_matches: 1000
    })

    for (const match of matches.matches) {
      const existing = report.sensitive_files.find(f => f.path === match.path)
      if (existing) {
        existing.matches.push(pattern)
      } else {
        report.sensitive_files.push({ path: match.path, matches: [pattern] })
      }
    }
  }

  // Step 3: Find large files
  const rootStats = await client.files.stat(searchPath)
  report.total_size = rootStats.size

  for (const file of allFiles.matches) {
    if (file.type === 'file' && file.size > auditConfig.largeFileThreshold) {
      report.large_files.push({ path: file.path, size: file.size })
    }
  }

  // Step 4: Check journal for recent mutations
  const recentChanges = await client.files.journal.query({
    path: searchPath,
    limit: 1000
  })

  // Step 5: Get health status
  const health = await client.files.health.check()

  return {
    report,
    health: health.status,
    journal_entries: recentChanges.total,
    generated_at: new Date().toISOString()
  }
}

// Usage
const audit = await auditFilesystem('app/', {
  sensitivePatterns: [
    'password\\s*=',
    'api[_-]?key\\s*=',
    'secret\\s*=',
    'private[_-]?key'
  ],
  largeFileThreshold: 104857600, // 100MB
  staleDays: 90
})

console.log(`Audit complete: ${audit.report.sensitive_files.length} sensitive files found`)
```

---

## Quick Reference

### Endpoint Groups Summary

| Group | Base Path | Methods | Description |
|-------|-----------|---------|-------------|
| **Files (v0)** | `/{path}` | GET, PUT, PATCH, DELETE, HEAD, OPTIONS | Legacy file operations |
| **Files (v1)** | `/api/v1/files/{path}` | GET, POST, PUT, PATCH, DELETE | Modern file operations |
| **File Operations** | `/api/v1/files/*` | Various | append, chmod, chown, copy, glob, grep, move, realpath, stat |
| **Downloads** | `/?download_history`, `/api/v1/downloads`, `/{dir}?download` | GET | Download management |
| **Archives** | `/?extraction_history`, `/api/v1/extractions`, `/{archive}?extract*` | GET | Archive extraction and preview |
| **Backends** | `/api/v1/backends/*` | GET, POST, PUT, DELETE | 60+ cloud storage providers |
| **Health** | `/api/v1/files/health` | GET | Service health check |
| **Journal** | `/api/v1/journal/*` | GET, POST | File mutation tracking |
| **Mounts** | `/api/v1/mounts/*` | GET, POST, PATCH, DELETE | FUSE filesystem mounts |
| **System** | `/api/v1/version` | GET | API version info |
| **Images** | `/{image}?thumbnail` | GET | Image processing |
| **Remote Access** | `/{path}?type=*` | GET, PUT | FTP, Git, S3, SSH, WebDAV |
| **WebDAV** | `/{path}` | OPTIONS, COPY, MOVE, LOCK, UNLOCK, PROPFIND, PROPPATCH | WebDAV protocol |
| **Directories** | `/{path}` | MKCOL | Directory creation |
| **Authentication** | `/{path}` | CHECKAUTH, LOGOUT | Auth management |
| **Search** | `/{directory}?q` | GET | File search |

### Essential SDK Methods by Group

#### Files (Core)
```
client.files.listDirectory(path, options)      // GET /{path}
client.files.upload(path)                       // PUT /{path}
client.files.patch(path, range?, data?)        // PATCH /{path}
client.files.deleteRecursive(path)              // DELETE /{path}
client.files.getMetadata(path)                  // HEAD /{path}
client.files.touch(path, touch)                // PUT /{path}?touch
```

#### Files (v1 API)
```
client.files.get(path, options)                 // GET /api/v1/files/{path}
client.files.operate(path, options)             // POST /api/v1/files/{path}
client.files.put(path, options)                 // PUT /api/v1/files/{path}
client.files.patchApi(path, options)            // PATCH /api/v1/files/{path}
client.files.delete(path, options)              // DELETE /api/v1/files/{path}
client.files.append(path, options)              // PUT /api/v1/files/append/{path}
client.files.chmod(path, chmod)                 // PATCH /api/v1/files/chmod/{path}
client.files.chown(path, chown)                 // PATCH /api/v1/files/chown/{path}
client.files.copy(path, dest, options)          // POST /api/v1/files/copy/{path}
client.files.move(path, dest, options)          // POST /api/v1/files/move/{path}
client.files.glob(path, options)                // GET /api/v1/files/glob/{path}
client.files.grep(path, options)                // GET /api/v1/files/grep/{path}
client.files.realpath(path)                     // GET /api/v1/files/realpath/{path}
client.files.stat(path)                         // GET /api/v1/files/stat/{path}
client.files.search(directory, options)         // GET /{directory}?q
```

#### Downloads
```
client.files.downloads.getHistory(download_history)  // GET /?download_history
client.files.downloads.listGlobal()                   // GET /api/v1/downloads
client.files.downloads.fetch(dir, download, ...)      // GET /{directory}?download
client.files.downloads.listActive(dir, downloads)     // GET /{directory}?downloads
```

#### Archives
```
client.files.archives.getHistory(extraction_history)  // GET /?extraction_history
client.files.archives.listActive(extractions)          // GET /?extractions
client.files.archives.listGlobal()                     // GET /api/v1/extractions
client.files.archives.extract(archive, extract, ...)   // GET /{archive}?extract
client.files.archives.extractFile(archive, ...)        // GET /{archive}?extract_file
client.files.archives.preview(archive, preview?)       // GET /{archive}?preview
client.files.archives.viewFile(archive, preview)       // GET /{archive}?view_file
client.files.archives.downloadAsZip(dir, zip)          // GET /{directory}?zip
```

#### Backends
```
client.files.backends.list()                           // GET /api/v1/backends
client.files.backends.getDetails(id)                   // GET /api/v1/backends/{id}
client.files.backends.update(id, data)                 // PUT /api/v1/backends/{id}
client.files.backends.disconnect(id)                   // DELETE /api/v1/backends/{id}
client.files.backends.testConnection(id)               // GET /api/v1/backends/{id}/test
client.files.backends.connectS3(data)                  // POST /api/v1/backends/s3
client.files.backends.connectDrive(data)               // POST /api/v1/backends/drive
client.files.backends.connectDropbox(data)             // POST /api/v1/backends/dropbox
client.files.backends.connectOnedrive(data)            // POST /api/v1/backends/onedrive
client.files.backends.connectAzureblob(data)           // POST /api/v1/backends/azureblob
// ... 60+ more connect methods following same pattern
```

#### Health
```
client.files.health.check()                            // GET /api/v1/files/health
```

#### Journal
```
client.files.journal.query(options)                    // GET /api/v1/journal
client.files.journal.flush()                           // POST /api/v1/journal/flush
client.files.journal.getStats()                        // GET /api/v1/journal/stats
```

#### Mounts
```
client.files.mounts.list(options)                      // GET /api/v1/mounts
client.files.mounts.create(data)                       // POST /api/v1/mounts
client.files.mounts.getDetails(id)                     // GET /api/v1/mounts/{id}
client.files.mounts.update(id, data)                   // PATCH /api/v1/mounts/{id}
client.files.mounts.unmount(id)                        // DELETE /api/v1/mounts/{id}
```

#### System
```
client.files.system.getApiVersion()                    // GET /api/v1/version
```

#### Images
```
client.files.images.process(image, thumbnail, options) // GET /{image}?thumbnail
```

#### Remote Access
```
// Access files from remote protocols (Git, S3, SSH, FTP, WebDAV) via unified get/put
// See Section 7 for detailed examples per protocol
client.files.get(path, { type, server, ... })           // GET /{path}?type=*
client.files.put(path, { type, server, ... })           // PUT /{path}?type=*
```

#### WebDAV Operations
```
client.files.webdav.getOptions(path)                   // OPTIONS /{path}
client.files.webdav.copyResource(path, dest, depth?)   // COPY /{path}
client.files.webdav.moveResource(path, dest)           // MOVE /{path}
client.files.webdav.lockResource(path, depth?)         // LOCK /{path}
client.files.webdav.unlockResource(path, token)        // UNLOCK /{path}
client.files.webdav.propfindResource(path, depth?)     // PROPFIND /{path}
client.files.webdav.proppatchResource(path)            // PROPPATCH /{path}
```

#### Directories
```
client.files.directories.create(path)                  // MKCOL /{path}
```

#### Authentication
```
client.files.authentication.checkAuth(path)            // CHECKAUTH /{path}
client.files.authentication.logout(path)               // LOGOUT /{path}
```

### Response Format Conventions

All responses follow consistent JSON structures:

**Success responses** include the operation result with relevant metadata:
```
{
  "status": "ok",
  "data": {}
}
```

**Error responses** include error details:
```
{
  "error": {
    "code": "NOT_FOUND",
    "message": "File not found: /path/to/file",
    "status": 404
  }
}
```

**List responses** include pagination metadata:
```
{
  "items": [],
  "total": 0,
  "has_more": false
}
```

### Common Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `json` | string | Return JSON instead of HTML |
| `backend` | string | Target specific backend |
| `hash` | string | Include file hash (sha256, md5) |
| `sort` | string | Sort field (name, size, modTime) |
| `order` | string | Sort order (asc, desc) |
| `limit` | integer | Max results to return |
| `overwrite` | string | Allow overwriting existing files |
| `append` | string | Append to existing file |
| `download` | string | Force download (Content-Disposition) |
| `preview` | string | Preview content or list |
| `contents` | string | Include file contents |
| `stat` | string | Include file statistics |
| `history` | string | Include version history |

### Supported Backend Types (60+)

Major categories with examples:

**Cloud Storage**: s3, drive, dropbox, onedrive, box, pcloud, mega, b2, google-cloud-storage, azureblob, azurefiles, swift, oracleobjectstorage, qingstor

**File Transfer**: ftp, sftp, webdav, http, smb, hdfs

**Developer Platforms**: git (GitHub, GitLab, Bitbucket), seafile, koofr

**Media Services**: cloudinary, imagekit, google-photos

**Decentralized**: storj, tardigrade, sia

**Utility**: alias, cache, chunker, combine, compress, crypt, hasher, memory, union

**Regional/Specialized**: yandex, mailru, jottacloud, hidrive, fichier, filefabric, filescom, gofile, internetarchive, linkbox, netstorage, opendrive, pikpak, pixeldrain, premiumizeme, protondrive, putio, quatrix, sugarsync, ulozto, uptobox, iclouddrive, zoho
```