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

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

import type { ObservationClient } from '../core/client';
import type { Terms, User, UserStats } from '../types';
export declare class Users {
    #private;
    /**
     * @internal
     */
    constructor(client: ObservationClient);
    /**
     * Retrieves the current terms of service and privacy policy.
     * This is a public endpoint and does not require authentication.
     *
     * @returns A promise that resolves to the terms and privacy policy documents.
     * @throws {ApiError} If the request fails.
     */
    getTerms(): Promise<Terms>;
    /**
     * Registers a new user account.
     * This is a public endpoint and does not require authentication.
     *
     * @param details - The registration details, including name, email, and password.
     * @param appName - The name of the application registering the user.
     * @param appVersion - The version of the application.
     * @returns A promise that resolves to the newly created user's public details.
     * @throws {ApiError} If the registration fails (e.g., email already exists).
     */
    register(details: {
        name: string;
        email: string;
        password: string;
        is_mail_allowed?: boolean;
        country?: string;
    }, appName: string, appVersion: string): Promise<{
        name: string;
        email: string;
        permalink: string;
        country: string;
    }>;
    /**
     * Sends a password reset email to a user.
     * This is a public endpoint and does not require authentication.
     *
     * @param email The user's email address.
     * @returns A promise that resolves to an object with a confirmation message.
     * @throws {ApiError} If the request fails.
     */
    resetPassword(email: string): Promise<{
        detail: string;
    }>;
    /**
     * Gets the full profile details of the current authenticated user.
     *
     * @returns A promise that resolves to the current user's full profile object.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    getInfo(): Promise<User>;
    /**
     * Updates the profile details of the current authenticated user.
     *
     * @param details - The details to update (name and/or country).
     * @returns A promise that resolves to the updated user object.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    updateInfo(details: {
        name: string;
        country?: string;
    }): Promise<User>;
    /**
     * Resends the email confirmation to the current authenticated user.
     *
     * @returns A promise that resolves to an object with a confirmation message.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    resendEmailConfirmation(): Promise<{
        detail: string;
    }>;
    /**
     * Gets aggregated observation statistics for the current authenticated user.
     *
     * @param params - The aggregation parameters (by day, month, or year, with optional date range).
     * @returns A promise that resolves to the user's statistics.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    getStats(params: {
        aggregation: 'day' | 'month' | 'year';
        start_date?: string;
        end_date?: string;
    }): Promise<UserStats>;
    /**
     * Gets a magic login link key for the current authenticated user.
     * This key can be used to log in without a password.
     *
     * @returns A promise that resolves to an object containing the magic login key (`sesame`).
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    getMagicLoginLink(): Promise<{
        sesame: string;
    }>;
    /**
     * Gets the URL of the current user's avatar.
     *
     * @returns A promise that resolves to an object with the avatar URL, or null if not set.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    getAvatar(): Promise<{
        avatar: string | null;
    }>;
    /**
     * Uploads a new avatar for the current user.
     * The image must be a square JPG, max 1000x1000px.
     *
     * @param avatar - A Blob or Buffer representing the image.
     * @returns A promise that resolves to an object with the new avatar URL.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the upload fails.
     */
    updateAvatar(avatar: Blob | Buffer): Promise<{
        avatar: string | null;
    }>;
    /**
     * Deletes the current user's avatar.
     *
     * @returns A promise that resolves to an object with a null avatar URL.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    deleteAvatar(): Promise<{
        avatar: string | null;
    }>;
}