import type { TaggableTable } from '@stacksjs/orm';
/**
 * Which table the `taggable_models` pivot points at (stacksjs/stacks#2579).
 *
 * `tags`, not `taggables`. The four aggregates below joined `taggables`, and
 * every writer of that pivot writes a `tags` id: the dashboard validates
 * `tagIds` against `tags`, writes them in `syncPostRelations`, reads them back
 * in `PostIndexAction`, and counts them in `TagIndexAction`. The migration's own
 * comment says `taggables` and is wrong too.
 *
 * `taggables` is a real table, but a different mechanism - the `taggable` trait
 * in `@stacksjs/orm` writes tag names straight into it with no pivot row at
 * all. Joining the pivot to it produced a silent empty result set, or worse, a
 * row whose id happened to collide.
 */
/**
 * Fetch a tag by its ID
 *
 * @param id The ID of the tag to fetch
 * @returns The tag record if found
 */
export declare function fetchTagById(id: number): Promise<TaggableTable | undefined>;
/**
 * Fetch all tags
 *
 * @returns An array of tag records
 */
export declare function fetchTags(): Promise<TaggableTable[]>;
/**
 * Find a tag by name or create it if it doesn't exist
 *
 * @param name The name of the tag to find or create
 * @param taggableType Type of the taggable entity
 * @param description Optional description for the tag
 * @returns The existing or newly created tag
 */
export declare function firstOrCreate(name: string, taggableType: string, description?: string): Promise<TaggableTable>;
/**
 * Count the number of posts that have been tagged
 *
 * @param taggableType The type of entity to count (e.g. 'posts')
 * @returns The count of tagged posts
 */
export declare function countTaggedPosts(taggableType: string): Promise<number>;
/**
 * Count the total number of tags in the system
 *
 * @returns The total count of tags
 */
export declare function countTotalTags(): Promise<number>;
/**
 * Find the most used tag in the system
 *
 * @param taggableType Optional type to filter by (e.g. 'posts', 'articles')
 * @returns The most used tag name and its count
 */
export declare function findMostUsedTag(taggableType?: string): Promise<{ name: string, count: number } | null>;
/**
 * Find the least used tag in the system
 *
 * @returns The least used tag name and its count
 */
export declare function findLeastUsedTag(): Promise<{ name: string, count: number } | null>;
/**
 * Fetch tags with their post counts
 *
 * @returns Array of tags with their post counts
 */
export declare function fetchTagsWithPostCounts(): Promise<Array<{ name: string, postCount: number }>>;
/**
 * Fetch tag distribution data for a donut graph
 *
 * @returns Array of tags with their counts and percentages
 */
export declare function fetchTagDistribution(): Promise<Array<{ name: string, count: number, percentage: number }>>;