node-hitomi/distribution/types/managers/gallery.d.ts

Hitomi.la API for Node.js

import { Gallery, GalleryReference } from '../structures/gallery.js';
import { Base } from '../internal/base.js';
import { Tag } from '../structures/tag.js';
import { Hitomi } from '../hitomi.js';

/**
 * Sort orders for listing galleries.
 *
 * @enum {string}
 * @readonly
 * @see {@link GalleryOptions.orderBy}
 */
declare enum SortType {
	DateAdded = 'added',
	DatePublished = 'published',
	Random = 'random',
	PopularityDay = 'today',
	PopularityWeek = 'week',
	PopularityMonth = 'month',
	PopularityYear = 'year'
}
/**
 * Pagination options for listing galleries.
 *
 * @see {@link GalleryOptions.page}
 */
interface PageOptions {
	/**
	 * Zero-based page index.
	 *
	 * @default 0
	 */
	index?: number;
	/**
	 * Number of galleries per page.
	 *
	 * @default 25
	 */
	size?: number;
}
/**
 * Search and filter options for listing galleries.
 *
 * @see {@link GalleryManager.list}
 */
interface GalleryOptions {
	/**
	 * Tags to filter results by.
	 */
	tags?: Tag[];
	/**
	 * The title keyword to search for.
	 */
	title?: string;
	/**
	 * The sort type to order by.
	 *
	 * @default SortType.DateAdded
	 */
	orderBy?: SortType;
	/**
	 * Pagination options.
	 */
	page?: PageOptions;
}
/**
 * A manager for retrieving and listing galleries.
 *
 * @see {@link Hitomi}
 */
declare class GalleryManager extends Base {
	/**
	 * Retrieves a gallery by its unique identifier.
	 *
	 * @param {number} id The unique gallery identifier.
	 * @returns {Promise<Gallery>} A `Promise` that resolves to the matching gallery.
	 * @see {@link Gallery}
	 */
	retrieve(id: number): Promise<Gallery>;
	/**
	 * Lists gallery references matching the specified search criteria.
	 *
	 * When `options.page` is provided, only one non-language tag (optionally combined with a language tag) is allowed, and negative tags are not supported.
	 *
	 * When using a popularity-based sort in `options.orderBy`, the number of returned galleries may vary.
	 *
	 * @param {GalleryOptions} [options] The search and filter options.
	 * @returns {Promise<GalleryReference[]>} A `Promise` that resolves to matching gallery references.
	 * @throws {HitomiError} If `page` is used with multiple tags or any negative tag.
	 * @see {@link GalleryReference}
	 * @see {@link SortType}
	 */
	list(options?: GalleryOptions): Promise<GalleryReference[]>;
}

export { GalleryManager, SortType };
export type { GalleryOptions, PageOptions };