name = "red-dress.jpg"                                  exact name (case-sensitive)
name : "red-dress"                                      name begins with red-dress
name HAS "red dress"                                    full-text: contains red AND dress (any case)
id = "64fb1c2d8a7b4c1234567890"                         single file/folder by id

createdAt > "7d"                                        uploaded in last 7 days
createdAt < 2020-01-01                                  uploaded before Jan 1 2020 (00:00 UTC)
updatedAt >= "2024-06-01T00:00:00"                      modified on/after a timestamp
createdAt > "7d" AND size > "2mb"                       recent AND large

size <= "1mb"                                           1MB or smaller
width > 500 AND height > 500                            at least 500x500 (images)
format = "png"                                          PNG files
format IN ["jpg", "webp"]                               JPG or WebP

tags IN ["sale", "summer"]                              has sale OR summer (tags or AITags)
tags NOT IN ["draft"]                                   excludes draft
tags HAS "sale"                                         full-text token match (sales, summer-sale…)
tags EXISTS                                             has at least one tag
tags NOT EXISTS                                         untagged files

type = "file"                                           files only
private = true                                          private files
published = false                                       drafts / unpublished
transparency = true                                     images with an alpha layer

path = "/sales-banner/"                                 exactly this folder, no subfolders
path : "/sales-banner/"                                 this folder AND its subfolders
format = "png" AND path : "/sales-banner/"              PNGs under a folder tree

"customMetadata.category" IN ["clothing", "accessories"]
"customMetadata.rating" > 4.3
"customMetadata.active" = true
"customMetadata.description" HAS "red"
"embeddedMetadata.DateTimeOriginal" > "1y"
"embeddedMetadata.LocationTaken" = "40,100 5km"

(size < "1mb" AND width > 500) OR (tags IN ["summer-sale", "banner"])

const fields = await client.customMetadataFields.list();
// each: { id, name, label, schema: { type: 'Text' | 'Number' | 'Date' | 'Boolean' | 'SingleSelect' | 'MultiSelect', ... } }
const brand = fields.find((f) => f.name === 'brand' || f.label === 'Brand');
if (!brand) throw new Error('No "brand" custom metadata field is defined');

const result = await client.assets.list({
  searchQuery: 'type = "file" AND "customMetadata.brand" = "nike"',
  limit: 100,
});

const files = await client.assets.list({ type: 'file', path: '/uploads', limit: 100 });
//    ^ File[] — fileId, size, url are all available without narrowing

const result = await client.assets.list({
  searchQuery: 'type = "file" AND createdAt >= "7d" AND size > "2mb"',
  limit: 100,
});
const files = [];
for (const item of result) {
  if (item.type === 'file') {
    files.push({ name: item.name, fileId: item.fileId, size: item.size });
  }
}

const rows = result.map((item) => {
  if (item.type === 'folder') {
    return { name: item.name, kind: 'folder', path: item.folderPath }; // item: Folder
  }
  return { name: item.name, kind: 'file', path: item.filePath, size: item.size, url: item.url }; // item: File
});

const result = await client.assets.list({
  searchQuery: 'name HAS "red dress"',
  sort: 'DESC_RELEVANCE',
  limit: 20,
});

for (let skip = 0; ; skip += 100) {
  const page = await client.assets.list({
    searchQuery: 'type = "file" AND tags IN ["sale", "summer"]',
    skip,
    limit: 100,
  });
  if (!page.length) break;
  for (const item of page) {
    if (item.type === 'file') {
      // item narrowed to File
    }
  }
}