observation-js/dist/lib/challenges.d.ts

A fully-typed TypeScript client for the waarneming.nl API.

import type { ObservationClient } from '../core/client';
import type { Challenge, ChallengeListParams, ChallengeRanking, MarkAsSeenResponse, Paginated, SubscribeResponse } from '../types';
export declare class Challenges {
    #private;
    /**
     * @internal
     */
    constructor(client: ObservationClient);
    /**
     * Fetches a list of challenges, which can be filtered by various parameters.
     * This endpoint is public, but results may differ for authenticated users.
     *
     * @param params - Optional parameters to filter the challenges.
     * @returns A promise that resolves to a paginated list of challenge objects.
     * @throws {ApiError} If the request fails.
     */
    list(params?: ChallengeListParams): Promise<Paginated<Challenge>>;
    /**
     * Fetches the details of a specific challenge by its ID.
     * This endpoint is public, but results may differ for authenticated users.
     *
     * @param id - The unique identifier of the challenge.
     * @returns A promise that resolves to the challenge details.
     * @throws {ApiError} If the request fails.
     */
    get(id: number): Promise<Challenge>;
    /**
     * Fetches the user ranking for a specific challenge.
     *
     * @param id - The unique identifier of the challenge.
     * @param by - The criteria to rank by, either 'species' or 'observations'.
     * @returns A promise that resolves to the challenge ranking data.
     * @throws {ApiError} If the request fails.
     */
    getRanking(id: number, by: 'species' | 'observations'): Promise<ChallengeRanking>;
    /**
     * Gets all the IDs of challenges that a specific observation contributes to.
     *
     * @param observationId - The unique identifier of the observation.
     * @returns A promise that resolves to a paginated list of challenge IDs.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    getForObservation(observationId: number): Promise<Paginated<{
        id: number;
    }>>;
    /**
     * Subscribes the authenticated user to a challenge, or unsubscribes them.
     *
     * @param id - The unique identifier of the challenge.
     * @param isSubscribed - Set to `true` to subscribe, `false` to unsubscribe.
     * @returns A promise that resolves to the updated subscription status.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    subscribe(id: number, isSubscribed: boolean): Promise<SubscribeResponse>;
    /**
     * Marks a piece of challenge content (e.g., instructions, results) as "seen" by the authenticated user.
     *
     * @param contentId - The unique identifier of the challenge content.
     * @returns A promise that resolves to an object with the `last_seen` timestamp.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    markContentAsSeen(contentId: number): Promise<MarkAsSeenResponse>;
}