observation-js
Version:
A fully-typed TypeScript client for the waarneming.nl API.
237 lines (236 loc) • 9.55 kB
JavaScript
export class Groups {
#client;
/**
* @internal
*/
constructor(client) {
this.#client = client;
}
/**
* Fetches the groups for the current authenticated user.
*
* @returns A promise that resolves to a paginated list of the user's groups.
* @throws {AuthenticationError} If the request is not authenticated.
* @throws {ApiError} If the request fails.
*/
async list() {
return this.#client.request('user/groups/');
}
/**
* Fetches the details of a specific group by its ID.
* The authenticated user must be a member of the group.
*
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to the group object.
* @throws {AuthenticationError} If the user is not a member or not authenticated.
* @throws {ApiError} If the request fails.
*/
async get(groupId) {
return this.#client.request(`groups/${groupId}`);
}
/**
* Fetches a public summary of a group using an invite code.
* This does not require authentication.
*
* @param groupId The unique identifier of the group.
* @param inviteCode The invite code for the group.
* @returns A promise that resolves to the group's public summary.
* @throws {ApiError} If the group or invite code is invalid.
*/
async getSummary(groupId, inviteCode) {
return this.#client.publicRequest(`groups/${groupId}/summary/${inviteCode}/`);
}
/**
* Creates a new group.
*
* @param name The name of the new group.
* @param photo The group's photo/avatar as a Blob or Buffer.
* @returns A promise that resolves to the newly created group object.
* @throws {AuthenticationError} If the request is not authenticated.
* @throws {ApiError} If the request fails.
*/
async create(name, photo) {
const formData = new FormData();
formData.append('name', name);
formData.append('photo', new Blob([photo]));
return this.#client.request('groups/create/', {
method: 'POST',
body: formData,
});
}
/**
* Updates an existing group's details.
* The authenticated user must be an admin of the group.
*
* @param groupId The unique identifier of the group to update.
* @param data An object containing the data to update (name and/or photo).
* @returns A promise that resolves to the updated group object.
* @throws {AuthenticationError} If the user is not an admin or not authenticated.
* @throws {ApiError} If the request fails.
*/
async update(groupId, data) {
const formData = new FormData();
if (data.name)
formData.append('name', data.name);
if (data.photo)
formData.append('photo', new Blob([data.photo]));
return this.#client.request(`groups/${groupId}`, {
method: 'PATCH',
body: formData,
});
}
/**
* Deletes a group.
* The authenticated user must be an admin of the group.
*
* @param groupId The unique identifier of the group to delete.
* @returns A promise that resolves when the group is successfully deleted.
* @throws {AuthenticationError} If the user is not an admin or not authenticated.
* @throws {ApiError} If the request fails.
*/
async delete(groupId) {
await this.#client.request(`groups/${groupId}`, {
method: 'DELETE',
});
}
/**
* Renews the invite code for a group.
* The authenticated user must be an admin of the group.
*
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to the updated group object with a new invite link.
* @throws {AuthenticationError} If the user is not an admin or not authenticated.
* @throws {ApiError} If the request fails.
*/
async renewInviteCode(groupId) {
return this.#client.request(`groups/${groupId}/renew-invite-code/`, {
method: 'POST',
});
}
/**
* Joins a group using an invite code.
*
* @param groupId The unique identifier of the group to join.
* @param inviteCode The invite code for the group.
* @returns A promise that resolves when the user has successfully joined the group.
* @throws {AuthenticationError} If the request is not authenticated.
* @throws {ApiError} If the invite code is invalid or the request fails.
*/
async join(groupId, inviteCode) {
await this.#client.request(`groups/${groupId}/join/${inviteCode}/`, {
method: 'POST',
});
}
/**
* Leaves a group.
* The authenticated user must be a member of the group.
*
* @param groupId The unique identifier of the group to leave.
* @returns A promise that resolves when the user has successfully left the group.
* @throws {AuthenticationError} If the user is not a member or not authenticated.
* @throws {ApiError} If the request fails.
*/
async leave(groupId) {
await this.#client.request(`groups/${groupId}/leave/`, {
method: 'POST',
});
}
/**
* Removes a member from a group.
* The authenticated user must be an admin of the group.
*
* @param groupId The unique identifier of the group.
* @param memberId The unique identifier of the member to remove.
* @returns A promise that resolves when the member is successfully removed.
* @throws {AuthenticationError} If the user is not an admin or not authenticated.
* @throws {ApiError} If the request fails.
*/
async removeMember(groupId, memberId) {
await this.#client.request(`groups/${groupId}/members/${memberId}/`, {
method: 'DELETE',
});
}
/**
* Fetches the available challenge templates that can be used to create group challenges.
*
* @returns A promise that resolves to a paginated list of challenge templates.
* @throws {AuthenticationError} If the request is not authenticated.
* @throws {ApiError} If the request fails.
*/
async listChallengeTemplates() {
return this.#client.request('groups/challenge-templates/');
}
/**
* Fetches the challenges for a specific group.
* The authenticated user must be a member of the group.
*
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to a paginated list of challenges for the group.
* @throws {AuthenticationError} If the user is not a member or not authenticated.
* @throws {ApiError} If the request fails.
*/
async listChallenges(groupId) {
return this.#client.request(`groups/${groupId}/challenges/`);
}
/**
* Creates a new challenge for a group from a template.
* The authenticated user must be an admin of the group.
*
* @param groupId The unique identifier of the group.
* @param data An object containing the challenge details (template ID, start, and end times).
* @returns A promise that resolves to the newly created challenge.
* @throws {AuthenticationError} If the user is not an admin or not authenticated.
* @throws {ApiError} If the request fails.
*/
async createChallenge(groupId, data) {
return this.#client.request(`groups/${groupId}/challenges/`, {
method: 'POST',
body: JSON.stringify(data),
});
}
/**
* Updates an existing group challenge.
* The authenticated user must be an admin of the group.
*
* @param groupId The unique identifier of the group.
* @param challengeId The unique identifier of the challenge to update.
* @param data An object containing the data to update (start and/or end times).
* @returns A promise that resolves to the updated challenge.
* @throws {AuthenticationError} If the user is not an admin or not authenticated.
* @throws {ApiError} If the request fails.
*/
async updateChallenge(groupId, challengeId, data) {
return this.#client.request(`groups/${groupId}/challenges/${challengeId}/`, {
method: 'PATCH',
body: JSON.stringify(data),
});
}
/**
* Deletes a group challenge.
* The authenticated user must be an admin of the group.
*
* @param groupId The unique identifier of the group.
* @param challengeId The unique identifier of the challenge to delete.
* @returns A promise that resolves when the challenge is successfully deleted.
* @throws {AuthenticationError} If the user is not an admin or not authenticated.
* @throws {ApiError} If the request fails.
*/
async deleteChallenge(groupId, challengeId) {
await this.#client.request(`groups/${groupId}/challenges/${challengeId}/`, {
method: 'DELETE',
});
}
/**
* Fetches observations for a specific group.
* The authenticated user must be a member of the group.
*
* @param groupId The unique identifier of the group.
* @returns A promise that resolves to a list of observations.
* Note: This response is not paginated in the standard way.
* @throws {AuthenticationError} If the user is not a member or not authenticated.
* @throws {ApiError} If the request fails.
*/
async getObservations(groupId) {
return this.#client.request(`groups/${groupId}/observations/`);
}
}