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

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

import type { ObservationClient } from '../core/client';
import type { CreateObservationOptions, CreateObservationPayload, Observation, UpdateObservationPayload } from '../types';
interface ObservationSearchParams {
    limit?: number;
    offset?: number;
    ordering?: string;
    country?: string;
    modified_after?: string;
    observation_date_after?: string;
    observation_date_before?: string;
    species_group?: number;
    rarity?: number;
    user?: number;
    species?: number;
}
interface AroundPointParams extends ObservationSearchParams {
    lng: number;
    lat: number;
    radius_km?: number;
}
interface PaginatedResponse<T> {
    count: number;
    next: string | null;
    previous: string | null;
    results: T[];
}
export declare class Observations {
    #private;
    /**
     * @internal
     */
    constructor(client: ObservationClient);
    /**
     * Helper function to filter out undefined values from params
     * @private
     */
    private filterParams;
    /**
     * Retrieves a single observation by its ID.
     *
     * @param id The unique identifier of the observation.
     * @returns A promise that resolves to the observation object.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    get(id: number): Promise<Observation>;
    /**
     * Creates a new observation.
     *
     * @param payload - The core data for the new observation.
     * @param options - Optional parameters, including media files to upload synchronously.
     * @returns A promise that resolves to the newly created observation object.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    create(payload: CreateObservationPayload, options?: CreateObservationOptions): Promise<Observation>;
    /**
     * Updates an existing observation.
     *
     * @param id - The unique identifier of the observation to update.
     * @param payload - The data to update on the observation.
     * @param options - Optional parameters, including media files to upload synchronously.
     * @returns A promise that resolves to the updated observation object.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    update(id: number, payload: UpdateObservationPayload, options?: CreateObservationOptions): Promise<Observation>;
    /**
     * Deletes an observation by its ID.
     *
     * @param id The unique identifier of the observation to delete.
     * @returns A promise that resolves when the observation is successfully deleted.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    delete(id: number): Promise<void>;
    /**
     * Search/list observations with filtering options.
     * Note: General observation listing may not be available. Use more specific methods like getBySpecies, getByLocation, etc.
     *
     * @param params - Search and filtering parameters.
     * @returns A promise that resolves to a paginated list of observations.
     * @throws {ApiError} If the request fails.
     */
    search(params?: ObservationSearchParams): Promise<PaginatedResponse<Observation>>;
    /**
     * Retrieves observations for a specific species.
     *
     * @param speciesId - The unique identifier of the species.
     * @param params - Optional filtering parameters.
     * @returns A promise that resolves to a paginated list of observations.
     * @throws {ApiError} If the request fails.
     */
    getBySpecies(speciesId: number, params?: ObservationSearchParams): Promise<PaginatedResponse<Observation>>;
    /**
     * Retrieves related species observations for a specific species.
     * Requires authentication.
     *
     * @param speciesId - The unique identifier of the species.
     * @param params - Optional filtering parameters.
     * @returns A promise that resolves to a paginated list of observations.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    getRelatedBySpecies(speciesId: number, params?: ObservationSearchParams): Promise<PaginatedResponse<Observation>>;
    /**
     * Retrieves observations for a specific user.
     * If no userId is provided, returns observations for the authenticated user.
     * Requires authentication.
     *
     * @param userId - The unique identifier of the user (optional for current user).
     * @param params - Optional filtering parameters.
     * @returns A promise that resolves to a paginated list of observations.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    getByUser(userId?: number, params?: ObservationSearchParams): Promise<PaginatedResponse<Observation>>;
    /**
     * Retrieves observations for a specific location.
     *
     * @param locationId - The unique identifier of the location.
     * @param params - Optional filtering parameters.
     * @returns A promise that resolves to a paginated list of observations.
     * @throws {ApiError} If the request fails.
     */
    getByLocation(locationId: number, params?: ObservationSearchParams): Promise<PaginatedResponse<Observation>>;
    /**
     * Retrieves observations around a specific geographic point.
     *
     * @param params - Point coordinates and search parameters.
     * @returns A promise that resolves to a paginated list of observations.
     * @throws {ApiError} If the request fails.
     */
    getAroundPoint(params: AroundPointParams): Promise<PaginatedResponse<Observation>>;
    /**
     * Retrieves observations that were deleted after a specific timestamp.
     * Requires authentication.
     *
     * @param modifiedAfter - ISO timestamp to get deletions after this point.
     * @returns A promise that resolves to a list of deleted observation IDs.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    getDeleted(modifiedAfter: string): Promise<{
        results: number[];
    }>;
}
export {};