stihirus-reader/index.d.ts

Fetches author profile information and optionally poems from stihirus.ru

/**
 * Represents the statistics for an author.
 */
export interface StihirusAuthorStats {
    /** Total number of poems (best estimate from HTML or API count if poems fetched). */
    poems: number;
    /** Number of reviews sent by the author. */
    reviewsSent: number;
    /** Number of reviews received by the author. */
    reviewsReceived: number;
}

/**
 * Represents information about an author's collection.
 */
export interface StihirusCollectionInfo {
    /** Name of the collection. */
    name: string;
    /** Full URL to the collection page. */
    url: string;
}

/**
 * Represents the rubric (genre) of a poem.
 */
export interface StihirusPoemRubric {
    /** Name of the general rubric (genre). */
    name: string;
    /** Full URL to the rubric page, or null if not available. */
    url: string | null;
}

/**
 * Represents a single poem.
 */
export interface StihirusPoem {
    /** Poem's unique ID. */
    id: number;
    /** Poem's title (or '***' if untitled). */
    title: string;
    /** Full text of the poem. */
    text: string;
    /** Creation date/time string (e.g., "27.03.2025 20:19"). */
    created: string;
    /** The rubric (genre) the poem belongs to. */
    rubric: StihirusPoemRubric;
    /** Name of the author's collection the poem is in, or null if none. */
    collection: string | null;
    /** Number of likes. */
    rating: number;
    /** Number of comments. */
    commentsCount: number;
    /** URL to the poem's specific image, if any. */
    imageUrl: string | null;
    /** Whether the poem has a certificate. */
    hasCertificate: boolean;
}

/**
 * Represents the complete data structure for an author.
 */
export interface StihirusAuthorData {
    /** Author's unique ID. */
    authorId: number;
    /** Author's display name (from HTML). */
    username: string;
    /** The URL used to fetch the HTML profile page. */
    profileUrl: string;
    /** Username used in URLs/API calls (derived from the identifier). */
    canonicalUsername: string;
    /** Author's profile description. */
    description: string;
    /** URL to the author's avatar image, or null if none. */
    avatarUrl: string | null;
    /** URL to the author's profile header image, or null if none. */
    headerUrl: string | null;
    /** Author's status (e.g., 'новенький'). */
    status: string;
    /** Text indicating the last visit time (e.g., '5 минут назад'). */
    lastVisit: string;
    /** Author's statistics. */
    stats: StihirusAuthorStats;
    /** Array of author's collections. */
    collections: StihirusCollectionInfo[];
    /**
     * Array of author's poems.
     * This array will be empty if `fetchAllPoems` was set to `false` in the `getAuthorData` call.
     */
    poems: StihirusPoem[];
}

/**
 * Represents the structure of an error object returned on failure.
 */
export interface StihirusError {
    /** HTTP status code or custom error code (e.g., 404, 500, 400). */
    code: number;
    /** User-friendly error message. */
    message: string;
    /** Optional underlying error message (e.g., from fetch or API response). */
    originalMessage?: string;
}

/**
 * Represents a successful response from `getAuthorData`.
 */
export interface StihirusSuccessResponse {
    status: 'success';
    data: StihirusAuthorData;
}

/**
 * Represents an error response from `getAuthorData`.
 */
export interface StihirusErrorResponse {
    status: 'error';
    error: StihirusError;
}

/**
 * Represents the possible response types from `getAuthorData`.
 */
export type StihirusResponse = StihirusSuccessResponse | StihirusErrorResponse;

/**
 * Asynchronously fetches author data from stihirus.ru.
 *
 * @param identifier - The author identifier. Can be an Author ID (number), Username (string), Subdomain URL (string), or Path URL (string).
 * @param requestDelayMs - Optional. The delay in milliseconds between API requests when fetching multiple pages of poems. Only relevant if `fetchAllPoems` is `true`. Defaults to 500ms.
 * @param fetchAllPoems - Optional. Whether to fetch all poems via the API. If `false`, only profile information is fetched, and the `poems` array in the result will be empty. Defaults to `true`.
 * @returns A promise that resolves to an object indicating the outcome (`StihirusResponse`). Check the `status` field ('success' or 'error').
 */
export declare function getAuthorData(
    identifier: string | number,
    requestDelayMs?: number,
    fetchAllPoems?: boolean
): Promise<StihirusResponse>;