observation-js
Version:
A fully-typed TypeScript client for the waarneming.nl API.
161 lines (160 loc) • 6.25 kB
TypeScript
import { Badges } from '../lib/badges';
import { Challenges } from '../lib/challenges';
import { Countries } from '../lib/countries';
import { Exports } from '../lib/exports';
import { Groups } from '../lib/groups';
import { Languages } from '../lib/languages';
import { Locations } from '../lib/locations';
import { Lookups } from '../lib/lookups';
import { Media } from '../lib/media';
import { Nia } from '../lib/nia';
import { Observations } from '../lib/observations';
import { Regions } from '../lib/regions';
import { RegionSpeciesLists } from '../lib/regionSpeciesLists';
import { Sessions } from '../lib/sessions';
import { Species } from '../lib/species';
import { Users } from '../lib/users';
import type { ObservationClientOptions, PasswordGrantOptions, TokenResponse } from '../types';
import { InterceptorManager } from './interceptors';
type FetchOptions = RequestInit & {
params?: Record<string, string | number>;
clientCache?: boolean | {
ttl: number;
};
};
export declare class ObservationClient {
#private;
readonly observations: Observations;
readonly species: Species;
readonly regions: Regions;
readonly locations: Locations;
readonly regionSpeciesLists: RegionSpeciesLists;
readonly users: Users;
readonly countries: Countries;
readonly badges: Badges;
readonly groups: Groups;
readonly exports: Exports;
readonly languages: Languages;
readonly lookups: Lookups;
readonly nia: Nia;
readonly media: Media;
readonly sessions: Sessions;
readonly challenges: Challenges;
readonly interceptors: {
request: InterceptorManager<FetchOptions>;
response: InterceptorManager<Response>;
};
/**
* The main client for interacting with the Waarneming.nl API.
*
* @param options - Configuration options for the client.
*/
constructor(options?: ObservationClientOptions);
/**
* Sets the language for the `Accept-Language` header in all subsequent API requests.
* The default language is 'en'.
*
* @param language - The two-letter language code (e.g., 'nl', 'en', 'de').
*/
setLanguage(language: string): void;
/**
* Gets the base URL for the API.
* @returns The base URL.
* @internal
*/
getApiBaseUrl(): string;
/**
* Generates the authorization URL for the OAuth2 Authorization Code Grant flow.
* The user should be redirected to this URL to authorize the application.
*
* @param state - A random string to protect against CSRF attacks.
* @param scope - An array of scopes the application is requesting.
* @returns The full authorization URL to redirect the user to.
* @throws {Error} If the client options (clientId, redirectUri) are not configured.
*/
getAuthorizationUrl(state: string, scope: string[]): string;
/**
* Exchanges an authorization code for an access token using the Authorization Code Grant flow.
*
* @param code - The authorization code received from the callback URL after user authorization.
* @returns A promise that resolves to the token response from the API.
* @throws {AuthenticationError} If the token request fails.
* @throws {Error} If the client options are not configured.
*/
getAccessToken(code: string): Promise<TokenResponse>;
/**
* Fetches an access token using the Resource Owner Password Credentials Grant.
* Use this grant type only for trusted applications.
*
* @param options - The credentials for the password grant.
* @returns A promise that resolves to the token response.
* @throws {AuthenticationError} If the token request fails.
*/
getAccessTokenWithPassword(options: PasswordGrantOptions): Promise<TokenResponse>;
/**
* Refreshes an expired access token using a refresh token.
*
* @returns A promise that resolves to the new token response.
* @throws {AuthenticationError} If the refresh token request fails.
* @throws {Error} If the refresh token or client options are not available.
*/
refreshAccessToken(): Promise<TokenResponse>;
/**
* Manually sets the access token for the client to use in subsequent authenticated requests.
*
* @param token - The access token.
*/
setAccessToken(token: string): void;
/**
* Manually sets the refresh token for the client.
*
* @param token - The refresh token.
* @internal
*/
setRefreshToken(token: string): void;
/**
* Checks if an access token is currently set on the client.
*
* @returns `true` if an access token is set, `false` otherwise.
*/
hasAccessToken(): boolean;
/**
* Checks if a refresh token is currently set on the client.
*
* @returns `true` if a refresh token is set, `false` otherwise.
*/
hasRefreshToken(): boolean;
/**
* Gets the current access token.
*
* @returns The access token or null if not set.
* @internal
*/
getCurrentAccessToken(): string | null;
private _fetch;
private buildUrl;
private _coreRequestAndHandle;
private _coreRequest;
private _handleResponse;
/**
* Makes an authenticated request to the API.
* An access token must be set via `setAccessToken` or by using one of the authentication flows.
*
* @param endpoint - The API endpoint to request.
* @param options - Optional request options, including URL parameters.
* @returns A promise that resolves to the JSON response.
* @throws {AuthenticationError} If the access token is not set or the request is unauthorized.
* @throws {ApiError} If the API request fails for other reasons.
*/
request: <T>(endpoint: string, options?: FetchOptions) => Promise<T>;
/**
* Makes a public (unauthenticated) request to the API.
*
* @param endpoint - The API endpoint to request.
* @param options - Optional request options, including URL parameters.
* @returns A promise that resolves to the JSON response.
* @throws {ApiError} If the API request fails.
*/
publicRequest: <T>(endpoint: string, options?: FetchOptions) => Promise<T>;
}
export {};