observation-js
Version:
A fully-typed TypeScript client for the waarneming.nl API.
187 lines (186 loc) • 8.31 kB
TypeScript
import type { ObservationClient } from '../core/client';
import type { Challenge, ChallengeTemplate, Group, GroupSummary, Observation, Paginated } from '../types';
export declare class Groups {
#private;
/**
* @internal
*/
constructor(client: ObservationClient);
/**
* 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.
*/
list(): Promise<Paginated<Group>>;
/**
* 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.
*/
get(groupId: number): Promise<Group>;
/**
* 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.
*/
getSummary(groupId: number, inviteCode: string): Promise<GroupSummary>;
/**
* 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.
*/
create(name: string, photo: Blob | Buffer): Promise<Group>;
/**
* 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.
*/
update(groupId: number, data: {
name?: string;
photo?: Blob | Buffer;
}): Promise<Group>;
/**
* 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.
*/
delete(groupId: number): Promise<void>;
/**
* 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.
*/
renewInviteCode(groupId: number): Promise<Group>;
/**
* 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.
*/
join(groupId: number, inviteCode: string): Promise<void>;
/**
* 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.
*/
leave(groupId: number): Promise<void>;
/**
* 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.
*/
removeMember(groupId: number, memberId: number): Promise<void>;
/**
* 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.
*/
listChallengeTemplates(): Promise<Paginated<ChallengeTemplate>>;
/**
* 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.
*/
listChallenges(groupId: number): Promise<Paginated<Challenge>>;
/**
* 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.
*/
createChallenge(groupId: number, data: {
template: number;
start_date_time: string;
end_date_time: string;
}): Promise<Challenge>;
/**
* 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.
*/
updateChallenge(groupId: number, challengeId: number, data: {
start_date_time?: string;
end_date_time?: string;
}): Promise<Challenge>;
/**
* 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.
*/
deleteChallenge(groupId: number, challengeId: number): Promise<void>;
/**
* 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.
*/
getObservations(groupId: number): Promise<{
next: string | null;
previous: string | null;
results: Observation[];
}>;
}