observation-js
Version:
A fully-typed TypeScript client for the waarneming.nl API.
112 lines (111 loc) • 4.52 kB
JavaScript
export class Badges {
#client;
/**
* @internal
*/
constructor(client) {
this.#client = client;
}
/**
* Fetches a list of badges.
* - For unauthenticated users, this returns a list of public "onboarding" badges.
* - For authenticated users, this returns their personalized list of badges including progress.
*
* @returns A promise that resolves to a paginated list of badge objects.
* @throws {ApiError} If the request fails.
*/
async list() {
if (this.#client.hasAccessToken()) {
return this.#client.request('badges/');
}
return this.#client.publicRequest('badges/', {
method: 'GET',
clientCache: true,
});
}
/**
* Fetches the details of a specific badge by its ID.
* - For unauthenticated users, this returns the public details of the badge.
* - For authenticated users, this returns personalized details including their progress.
*
* @param id The unique identifier for the badge.
* @returns A promise that resolves to the badge object.
* @throws {ApiError} If the request fails.
*/
async get(id) {
const endpoint = `badges/${id}`;
if (this.#client.hasAccessToken()) {
return this.#client.request(endpoint);
}
return this.#client.publicRequest(endpoint, {
method: 'GET',
clientCache: true,
});
}
/**
* Gets all badge IDs that a specific observation contributes to.
*
* @param observationId The unique identifier for the observation.
* @returns A promise that resolves to a paginated list of badge IDs.
* @throws {AuthenticationError} If the request is not authenticated.
* @throws {ApiError} If the request fails.
*/
async getForObservation(observationId) {
return this.#client.request(`badges/observation/${observationId}/`);
}
/**
* Marks all regular badges as "seen" for the current user.
* This updates the `last_seen` timestamp for all of the user's regular badges.
*
* @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.
*/
async markAllAsSeen() {
return this.#client.request('badges/user-badge/seen/', { method: 'POST' });
}
/**
* Gets the `last_seen` timestamp for a specific regular user badge.
*
* @param userBadgeId The unique identifier for the user badge.
* @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.
*/
async getLastSeen(userBadgeId) {
return this.#client.request(`badges/user-badge/${userBadgeId}/seen/`);
}
/**
* Marks a specific regular user badge as "seen".
*
* @param userBadgeId The unique identifier for the user badge.
* @returns A promise that resolves to an object with the updated `last_seen` timestamp.
* @throws {AuthenticationError} If the request is not authenticated.
* @throws {ApiError} If the request fails.
*/
async markAsSeen(userBadgeId) {
return this.#client.request(`badges/user-badge/${userBadgeId}/seen/`, { method: 'POST' });
}
/**
* Gets the `last_seen` timestamp for a specific user season badge.
*
* @param userSeasonBadgeId The unique identifier for the user season badge.
* @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.
*/
async getSeasonLastSeen(userSeasonBadgeId) {
return this.#client.request(`badges/user-season-badge/${userSeasonBadgeId}/seen/`);
}
/**
* Marks a specific user season badge as "seen".
*
* @param userSeasonBadgeId The unique identifier for the user season badge.
* @returns A promise that resolves to an object with the updated `last_seen` timestamp.
* @throws {AuthenticationError} If the request is not authenticated.
* @throws {ApiError} If the request fails.
*/
async markSeasonAsSeen(userSeasonBadgeId) {
return this.#client.request(`badges/user-season-badge/${userSeasonBadgeId}/seen/`, { method: 'POST' });
}
}