Search API

/**
 * Search class with fluent interface for building queries
 */
interface Search {
  /** Set search expression using Cloudinary search syntax */
  expression(value: string): Search;
  /** Set maximum number of results to return */
  max_results(value: number): Search;
  /** Set pagination cursor for next page */
  next_cursor(value: string): Search;
  /** Sort results by field and direction */
  sort_by(key: string, value: 'asc' | 'desc'): Search;
  /** Add aggregation to the search */
  aggregate(value: string): Search;
  /** Include additional fields in results */
  with_field(value: string | string[]): Search;
  /** Alias for with_field */
  fields(value: string | string[]): Search;
  /** Execute the search query */
  execute(): Promise<SearchResponse>;
  /** Generate search URL with TTL */
  to_url(ttl?: number, next_cursor?: string, options?: any): string;
}

/**
 * Create new search instance
 */
const search: {
  /** Create search instance with expression */
  expression(value: string): Search;
  /** Create empty search instance */
  instance(): Search;
  /** Static methods for fluent initialization */
  max_results(value: number): Search;
  sort_by(key: string, value: 'asc' | 'desc'): Search;
  aggregate(value: string): Search;
  with_field(value: string | string[]): Search;
  fields(value: string | string[]): Search;
};

interface SearchResponse {
  /** Array of found resources */
  resources: SearchResource[];
  /** Total count of matching resources */
  total_count: number;
  /** Next pagination cursor */
  next_cursor?: string;
  /** Aggregations if requested */
  aggregations?: Record<string, any>;
  /** Search execution time */
  time: number;
  [key: string]: any;
}

interface SearchResource {
  public_id: string;
  filename: string;
  format: string;
  version: number;
  resource_type: string;
  type: string;
  created_at: string;
  uploaded_at: string;
  bytes: number;
  backup_bytes: number;
  width: number;
  height: number;
  aspect_ratio: number;
  pixels: number;
  url: string;
  secure_url: string;
  status: string;
  access_mode: string;
  access_control: string[];
  etag: string;
  created_by: Record<string, any>;
  uploaded_by: Record<string, any>;
  tags: string[];
  context?: Record<string, string>;
  metadata?: Record<string, string>;
  [key: string]: any;
}

const cloudinary = require('cloudinary');

// Basic search by tag
const results = await cloudinary.v2.search
  .expression('tags:landscape')
  .max_results(20)
  .execute();

console.log('Found', results.total_count, 'landscape images');

// Complex search with multiple criteria
const complexSearch = await cloudinary.v2.search
  .expression('resource_type:image AND tags:product AND width>500')
  .sort_by('created_at', 'desc')
  .with_field(['tags', 'context', 'metadata'])
  .max_results(50)
  .execute();

// Search with pagination
let allResults = [];
let cursor = null;

do {
  const page = await cloudinary.v2.search
    .expression('folder:products/*')
    .max_results(100)
    .next_cursor(cursor)
    .execute();
  
  allResults = allResults.concat(page.resources);
  cursor = page.next_cursor;
} while (cursor);

// Search with aggregations
const aggregatedResults = await cloudinary.v2.search
  .expression('resource_type:image')
  .aggregate('format')
  .aggregate('tags')
  .max_results(0) // Only get aggregations
  .execute();

console.log('Formats:', aggregatedResults.aggregations.format);

// Search by resource type
await cloudinary.v2.search.expression('resource_type:video').execute();

// Search by tags
await cloudinary.v2.search.expression('tags:product AND tags:featured').execute();

// Search by folder
await cloudinary.v2.search.expression('folder:uploads/2023/*').execute();

// Search by dimensions
await cloudinary.v2.search.expression('width>1000 AND height>800').execute();

// Search by format
await cloudinary.v2.search.expression('format:jpg OR format:png').execute();

// Search by upload date
await cloudinary.v2.search.expression('uploaded_at>1d').execute();

// Search by context metadata
await cloudinary.v2.search.expression('context.category=electronics').execute();

// Search by custom metadata
await cloudinary.v2.search.expression('metadata.alt_text=*').execute();

// Complex nested search
await cloudinary.v2.search.expression(
  '(tags:product OR tags:banner) AND resource_type:image AND width>300'
).execute();

/**
 * Search folders class for folder-specific searches
 */
interface SearchFolders {
  /** Set search expression for folders */
  expression(value: string): SearchFolders;
  /** Set maximum results */
  max_results(value: number): SearchFolders;
  /** Set pagination cursor */
  next_cursor(value: string): SearchFolders;
  /** Execute folder search */
  execute(): Promise<FolderSearchResponse>;
}

const search_folders: {
  expression(value: string): SearchFolders;
  instance(): SearchFolders;
};

interface FolderSearchResponse {
  /** Array of found folders */
  folders: Array<{
    name: string;
    path: string;
    [key: string]: any;
  }>;
  /** Total count */
  total_count: number;
  /** Next cursor */
  next_cursor?: string;
  [key: string]: any;
}

const cloudinary = require('cloudinary');

// Search for folders
const folderResults = await cloudinary.v2.search_folders
  .expression('name:product*')
  .max_results(20)
  .execute();

console.log('Found folders:', folderResults.folders.map(f => f.path));

interface Search {
  expression(value: string): Search;
  max_results(value: number): Search;
  next_cursor(value: string): Search;
  sort_by(key: string, value: 'asc' | 'desc'): Search;
  aggregate(value: string): Search;
  with_field(value: string | string[]): Search;
  fields(value: string | string[]): Search;
  execute(): Promise<SearchResponse>;
  to_url(ttl?: number, next_cursor?: string, options?: any): string;
}

interface SearchResponse {
  resources: SearchResource[];
  total_count: number;
  next_cursor?: string;
  aggregations?: Record<string, any>;
  time: number;
  [key: string]: any;
}

interface SearchResource {
  public_id: string;
  filename: string;
  format: string;
  version: number;
  resource_type: string;
  type: string;
  created_at: string;
  uploaded_at: string;
  bytes: number;
  width: number;
  height: number;
  url: string;
  secure_url: string;
  tags: string[];
  context?: Record<string, string>;
  metadata?: Record<string, string>;
  [key: string]: any;
}