umami-api-js 0.0.1

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,5 @@
+Lightweight alternative to [@umami/api-client](https://github.com/umami-software/api-client), forked from [osu-api-v2-js](https://github.com/TTTaevas/osu-api-v2-js)
+
+Please note that this package expects self-hosted instances of Umami, it is not built to work with Umami Cloud
+
+Please also note that this is currently being built mainly to serve as a component to my [taevas.xyz](https://codeberg.org/Taevas/taevas.xyz) project

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+export interface ValueAndPrev {
+    /** The actual value for the given time period */
+    value: number;
+    /** The value for the same *timespan* for the time period that ends where the time period for value starts  */
+    prev: number;
+}
+/** If the {@link API} throws an error, it should always be an {@link APIError}! */
+export declare class APIError extends Error {
+    message: string;
+    server: API["server"];
+    method: Parameters<API["request"]>[0];
+    endpoint: Parameters<API["request"]>[1];
+    parameters: Parameters<API["request"]>[2];
+    status_code?: number | undefined;
+    original_error?: Error | undefined;
+    /**
+     * @param message The reason why things didn't go as expected
+     * @param server The server to which the request was sent
+     * @param method The method used for this request (like "get", "post", etc...)
+     * @param endpoint The type of resource that was requested from the server
+     * @param parameters The filters that were used to specify what resource was wanted
+     * @param status_code The status code that was returned by the server, if there is one
+     * @param original_error The error that caused the api to throw an {@link APIError} in the first place, if there is one
+     */
+    constructor(message: string, server: API["server"], method: Parameters<API["request"]>[0], endpoint: Parameters<API["request"]>[1], parameters: Parameters<API["request"]>[2], status_code?: number | undefined, original_error?: Error | undefined);
+}
+/** An API instance is needed to make requests to the server! */
+export declare class API {
+    /** If you have account credentials, you might want to use this constructor */
+    constructor(username: API["username"], password: API["password"], settings?: Partial<API>);
+    /** If you are already in possession of an {@link API.token} and don't necessarily wish to be able to get a new one, you might want to use this constructor */
+    constructor(token: API["token"], settings?: Partial<API>);
+    private _token;
+    /** The key that allows you to talk with the API */
+    get token(): string;
+    set token(token: string);
+    private _token_type;
+    /** Should always be "Bearer" */
+    get token_type(): string;
+    set token_type(token: string);
+    private _expires;
+    /** The expiration date of your token */
+    get expires(): Date;
+    set expires(date: Date);
+    private _username;
+    /** The username of the account */
+    get username(): string;
+    set username(username: string);
+    private _password;
+    /** The password of the account */
+    get password(): string;
+    set password(password: string);
+    private _server;
+    /** The base URL where requests should land, **should include the `/api` portion if applicable** */
+    get server(): string;
+    set server(server: string);
+    private _headers;
+    /** Used in practically all requests, those are all the headers the package uses excluding `Authorization`, the one with the token */
+    get headers(): {
+        [key: string]: any;
+    };
+    set headers(headers: {
+        [key: string]: any;
+    });
+    private _user;
+    /** Information about the account that has been used to log in */
+    get user(): {
+        id: string;
+        username: string;
+        role: string;
+        createdAt: Date;
+        isAdmin: boolean;
+    };
+    set user(user: {
+        id: string;
+        username: string;
+        role: string;
+        createdAt: Date;
+        isAdmin: boolean;
+    });
+    private number_of_requests;
+    /** Has {@link API.setNewToken} been called and not yet returned anything? */
+    private is_setting_token;
+    /** If {@link API.setNewToken} has been called, you can wait for it to be done through this promise */
+    private token_promise;
+    /**
+     * This creates a new {@link API.token}, alongside a new {@link API.refresh_token} if arguments are provided or if a refresh_token already exists
+     * @remarks The API object requires a {@link API.username} and a {@link API.password} to successfully get any token
+     * @returns Whether or not the token has changed (this should never throw)
+     */
+    setNewToken(): Promise<boolean>;
+    private _set_token_on_401;
+    /** If true, upon failing a request due to a 401, it will call {@link API.setNewToken} (defaults to **true**) */
+    get set_token_on_401(): boolean;
+    set set_token_on_401(bool: boolean);
+    private _set_token_on_expires;
+    /**
+     * If true, the application will silently call {@link API.setNewToken} when the {@link API.token} is set to expire,
+     * as determined by {@link API.expires} (defaults to **false**)
+     */
+    get set_token_on_expires(): boolean;
+    set set_token_on_expires(enabled: boolean);
+    private _token_timer?;
+    get token_timer(): API["_token_timer"];
+    set token_timer(timer: NodeJS.Timeout);
+    /** Add, remove, change the timeout used for setting a new token automatically whenever certain properties change */
+    private updateTokenTimer;
+    private _verbose?;
+    /** Which events should be logged (defaults to **none**) */
+    get verbose(): "none" | "errors" | "all" | undefined;
+    set verbose(verbose: "none" | "errors" | "all" | undefined);
+    private _timeout;
+    /**
+     * The maximum **amount of seconds** requests should take before returning an answer (defaults to **20**)
+     * @remarks 0 means no maximum, no timeout
+     */
+    get timeout(): number;
+    set timeout(timeout: number);
+    private _signal?;
+    /** The `AbortSignal` used in every request */
+    get signal(): AbortSignal | undefined;
+    set signal(signal: AbortSignal | undefined);
+    private _retry_maximum_amount;
+    /**
+     * How many retries maximum before throwing an {@link APIError} (defaults to **4**)
+     * @remarks Pro tip: Set that to 0 to **completely** disable retries!
+     */
+    get retry_maximum_amount(): number;
+    set retry_maximum_amount(retry_maximum_amount: number);
+    private _retry_delay;
+    /** In seconds, how long should it wait after a request failed before retrying? (defaults to **2**) */
+    get retry_delay(): number;
+    set retry_delay(retry_delay: number);
+    private _retry_on_new_token;
+    /** Should it retry a request upon successfully setting a new token due to {@link API.set_token_on_401} being `true`? (defaults to **true**) */
+    get retry_on_new_token(): boolean;
+    set retry_on_new_token(retry_on_new_token: boolean);
+    private _retry_on_status_codes;
+    /** Upon failing a request and receiving a response, because of which received status code should the request be retried? (defaults to **[429]**) */
+    get retry_on_status_codes(): number[];
+    set retry_on_status_codes(retry_on_status_codes: number[]);
+    private _retry_on_timeout;
+    /** Should it retry a request if that request failed because it has been aborted by the {@link API.timeout}? (defaults to **false**) */
+    get retry_on_timeout(): boolean;
+    set retry_on_timeout(retry_on_timeout: boolean);
+    /**
+     * Use this instead of `console.log` to log any information
+     * @param is_error Is the logging happening because of an error?
+     * @param to_log Whatever you would put between the parentheses of `console.log()`
+     */
+    private log;
+    /**
+     * Use this instead of a straight `fetch` to connect to the server
+     * @param is_token_related Is the request related to getting a token? If so, it bypasses `token_promise`
+     * @param method The HTTP method https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods
+     * @param endpoint The endpoint, may or may not be listed on https://umami.is/docs/api
+     * @param parameters GET query in object form, or the request body if the method is not GET
+     * @param info Relevant only when `fetch` calls itself, avoid setting it
+     * @remarks Consider using the higher-level method called {@link API.request}
+     */
+    private fetch;
+    /**
+     * The function that directly communicates with the API! Almost every functions of the API object uses this function!
+     * @param method The type of request, each endpoint uses a specific one (if it uses multiple, the intent and parameters become different)
+     * @param endpoint What comes in the URL after `api/`, **DO NOT USE TEMPLATE LITERALS (\`) OR THE ADDITION OPERATOR (+), put everything separately for type safety**
+     * @param parameters The things to specify in the request, such as the beatmap_id when looking for a beatmap
+     * @param settings Additional settings **to add** to the current settings of the `fetch()` request
+     * @returns A Promise with the API's response
+     */
+    request(method: "get" | "post" | "put" | "delete", endpoint: Array<string | number>, parameters?: {
+        [k: string]: any;
+    }): Promise<any>;
+    getWebsiteStats(website_id: string, startAt: Date, endAt: Date): Promise<{
+        pageviews: ValueAndPrev;
+        visitors: ValueAndPrev;
+        visits: ValueAndPrev;
+        bounces: ValueAndPrev;
+        totaltime: ValueAndPrev;
+    }>;
+}

package/dist/index.js

@@ -0,0 +1,372 @@
+import { adaptParametersForGETRequests, correctType } from "./utilities.js";
+/** If the {@link API} throws an error, it should always be an {@link APIError}! */
+export class APIError extends Error {
+    message;
+    server;
+    method;
+    endpoint;
+    parameters;
+    status_code;
+    original_error;
+    /**
+     * @param message The reason why things didn't go as expected
+     * @param server The server to which the request was sent
+     * @param method The method used for this request (like "get", "post", etc...)
+     * @param endpoint The type of resource that was requested from the server
+     * @param parameters The filters that were used to specify what resource was wanted
+     * @param status_code The status code that was returned by the server, if there is one
+     * @param original_error The error that caused the api to throw an {@link APIError} in the first place, if there is one
+     */
+    constructor(message, server, method, endpoint, parameters, status_code, original_error) {
+        super();
+        this.message = message;
+        this.server = server;
+        this.method = method;
+        this.endpoint = endpoint;
+        this.parameters = parameters;
+        this.status_code = status_code;
+        this.original_error = original_error;
+        if (this.parameters?.password) {
+            this.parameters.password = "<REDACTED>";
+        }
+    }
+}
+/** An API instance is needed to make requests to the server! */
+export class API {
+    constructor(username_or_token, password_or_settings, settings) {
+        settings ??= typeof password_or_settings !== "string" ? password_or_settings : undefined;
+        if (settings) {
+            /** Delete every property that is `undefined` so the class defaults aren't overwritten by `undefined` */
+            Object.keys(settings).forEach((key) => {
+                settings[key] === undefined ? delete settings[key] : {};
+            });
+            Object.assign(this, settings);
+        }
+        /** We want to set a new token instantly if account credentials have been provided */
+        if (typeof username_or_token === "string" && typeof password_or_settings === "string") {
+            this.username = username_or_token;
+            this.password = password_or_settings;
+            this.setNewToken();
+        }
+    }
+    _token = "";
+    /** The key that allows you to talk with the API */
+    get token() { return this._token; }
+    set token(token) { this._token = token; }
+    _token_type = "Bearer";
+    /** Should always be "Bearer" */
+    get token_type() { return this._token_type; }
+    set token_type(token) { this._token_type = token; }
+    _expires = new Date(new Date().getTime() + 24 * 60 * 60 * 1000); // 24 hours default, is set through getAndSetToken anyway
+    /** The expiration date of your token */
+    get expires() { return this._expires; }
+    set expires(date) {
+        this._expires = date;
+        this.updateTokenTimer();
+    }
+    // CLIENT INFO
+    _username = "";
+    /** The username of the account */
+    get username() { return this._username; }
+    set username(username) { this._username = username; }
+    _password = "";
+    /** The password of the account */
+    get password() { return this._password; }
+    set password(password) { this._password = password; }
+    _server = "";
+    /** The base URL where requests should land, **should include the `/api` portion if applicable** */
+    get server() { return this._server; }
+    set server(server) { this._server = server; }
+    _headers = {
+        "Accept": "application/json",
+        "Accept-Encoding": "gzip",
+        "Content-Type": "application/json",
+        "User-Agent": "umami-api-js (https://codeberg.org/Taevas/umami-api-js)",
+    };
+    /** Used in practically all requests, those are all the headers the package uses excluding `Authorization`, the one with the token */
+    get headers() { return this._headers; }
+    set headers(headers) { this._headers = headers; }
+    _user = {
+        id: "",
+        username: "",
+        role: "",
+        createdAt: new Date(),
+        isAdmin: false,
+    };
+    /** Information about the account that has been used to log in */
+    get user() { return this._user; }
+    set user(user) { this._user = user; }
+    number_of_requests = 0;
+    // TOKEN HANDLING
+    /** Has {@link API.setNewToken} been called and not yet returned anything? */
+    is_setting_token = false;
+    /** If {@link API.setNewToken} has been called, you can wait for it to be done through this promise */
+    token_promise = new Promise(r => r);
+    /**
+     * This creates a new {@link API.token}, alongside a new {@link API.refresh_token} if arguments are provided or if a refresh_token already exists
+     * @remarks The API object requires a {@link API.username} and a {@link API.password} to successfully get any token
+     * @returns Whether or not the token has changed (this should never throw)
+     */
+    async setNewToken() {
+        const old_token = this.token;
+        this.is_setting_token = true;
+        const body = {
+            username: this.username,
+            password: this.password,
+        };
+        this.token_promise = new Promise((resolve, reject) => {
+            this.fetch(true, "post", ["auth", "login"], body)
+                .then((response) => {
+                response.json()
+                    .then((json) => {
+                    if (!json.token) {
+                        const error_message = json.error_description ?? json.message ?? "No token obtained"; // Expect "Client authentication failed"
+                        this.log(true, "Unable to obtain a token! Here's what was received from the API:", json);
+                        reject(new APIError(error_message, this.server, "post", ["auth", "login"], body, response.status));
+                    }
+                    this.token_type = json.token_type;
+                    this.token = json.token;
+                    const expiration_date = new Date();
+                    expiration_date.setDate(expiration_date.getDate() + 1); // Assume 24 hours
+                    this.expires = expiration_date;
+                    resolve();
+                });
+            })
+                .catch(reject); // reject the promise with the received error instead of throwing (is it even useful?)
+        });
+        await this.token_promise;
+        this.is_setting_token = false;
+        if (old_token !== this.token)
+            this.log(false, "A new token has been set!");
+        return old_token !== this.token;
+    }
+    _set_token_on_401 = true;
+    /** If true, upon failing a request due to a 401, it will call {@link API.setNewToken} (defaults to **true**) */
+    get set_token_on_401() { return this._set_token_on_401; }
+    set set_token_on_401(bool) { this._set_token_on_401 = bool; }
+    _set_token_on_expires = false;
+    /**
+     * If true, the application will silently call {@link API.setNewToken} when the {@link API.token} is set to expire,
+     * as determined by {@link API.expires} (defaults to **false**)
+     */
+    get set_token_on_expires() { return this._set_token_on_expires; }
+    set set_token_on_expires(enabled) {
+        this._set_token_on_expires = enabled;
+        this.updateTokenTimer();
+    }
+    _token_timer;
+    get token_timer() { return this._token_timer; }
+    set token_timer(timer) {
+        // if a previous one already exists, clear it
+        if (this._token_timer) {
+            clearTimeout(this._token_timer);
+        }
+        this._token_timer = timer;
+        this._token_timer.unref(); // don't prevent exiting the program while this timeout is going on
+    }
+    /** Add, remove, change the timeout used for setting a new token automatically whenever certain properties change */
+    updateTokenTimer() {
+        if (this.expires && this.set_token_on_expires) {
+            const now = new Date();
+            const ms = this.expires.getTime() - now.getTime();
+            /**
+             * Let's say that we used a refresh token *after* the expiration time, our refresh token would naturally get updated
+             * However, if it is updated before the (local) expiration date is updated, then ms should be 0
+             * This should mean that, upon using a refresh token, we would use our new refresh token instantly...
+             * In other words, don't allow timeouts that would mean no timeout; {@link API.setNewToken} exists for that
+             */
+            if (ms <= 0) {
+                return undefined;
+            }
+            this.token_timer = setTimeout(() => {
+                try {
+                    this.setNewToken();
+                }
+                catch { }
+            }, ms);
+        }
+        else if (this._token_timer) {
+            clearTimeout(this._token_timer);
+        }
+    }
+    // CLIENT CONFIGURATION
+    _verbose = "none";
+    /** Which events should be logged (defaults to **none**) */
+    get verbose() { return this._verbose; }
+    set verbose(verbose) { this._verbose = verbose; }
+    _timeout = 20;
+    /**
+     * The maximum **amount of seconds** requests should take before returning an answer (defaults to **20**)
+     * @remarks 0 means no maximum, no timeout
+     */
+    get timeout() { return this._timeout; }
+    set timeout(timeout) { this._timeout = timeout; }
+    _signal;
+    /** The `AbortSignal` used in every request */
+    get signal() { return this._signal; }
+    set signal(signal) { this._signal = signal; }
+    // RETRIES
+    _retry_maximum_amount = 4;
+    /**
+     * How many retries maximum before throwing an {@link APIError} (defaults to **4**)
+     * @remarks Pro tip: Set that to 0 to **completely** disable retries!
+     */
+    get retry_maximum_amount() { return this._retry_maximum_amount; }
+    set retry_maximum_amount(retry_maximum_amount) { this._retry_maximum_amount = retry_maximum_amount; }
+    _retry_delay = 2;
+    /** In seconds, how long should it wait after a request failed before retrying? (defaults to **2**) */
+    get retry_delay() { return this._retry_delay; }
+    set retry_delay(retry_delay) { this._retry_delay = retry_delay; }
+    _retry_on_new_token = true;
+    /** Should it retry a request upon successfully setting a new token due to {@link API.set_token_on_401} being `true`? (defaults to **true**) */
+    get retry_on_new_token() { return this._retry_on_new_token; }
+    set retry_on_new_token(retry_on_new_token) { this._retry_on_new_token = retry_on_new_token; }
+    _retry_on_status_codes = [429];
+    /** Upon failing a request and receiving a response, because of which received status code should the request be retried? (defaults to **[429]**) */
+    get retry_on_status_codes() { return this._retry_on_status_codes; }
+    set retry_on_status_codes(retry_on_status_codes) { this._retry_on_status_codes = retry_on_status_codes; }
+    _retry_on_timeout = false;
+    /** Should it retry a request if that request failed because it has been aborted by the {@link API.timeout}? (defaults to **false**) */
+    get retry_on_timeout() { return this._retry_on_timeout; }
+    set retry_on_timeout(retry_on_timeout) { this._retry_on_timeout = retry_on_timeout; }
+    // OTHER METHODS
+    /**
+     * Use this instead of `console.log` to log any information
+     * @param is_error Is the logging happening because of an error?
+     * @param to_log Whatever you would put between the parentheses of `console.log()`
+     */
+    log(is_error, ...to_log) {
+        if (this.verbose !== "none" && is_error === true) {
+            console.error("umami api ->", ...to_log);
+        }
+        else if (this.verbose === "all") {
+            console.log("umami api ->", ...to_log);
+        }
+    }
+    /**
+     * Use this instead of a straight `fetch` to connect to the server
+     * @param is_token_related Is the request related to getting a token? If so, it bypasses `token_promise`
+     * @param method The HTTP method https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods
+     * @param endpoint The endpoint, may or may not be listed on https://umami.is/docs/api
+     * @param parameters GET query in object form, or the request body if the method is not GET
+     * @param info Relevant only when `fetch` calls itself, avoid setting it
+     * @remarks Consider using the higher-level method called {@link API.request}
+     */
+    async fetch(is_token_related, method, endpoint, parameters = {}, info = { number_try: 1, has_new_token: false }) {
+        let to_retry = false;
+        let error_object;
+        let error_code;
+        let error_message = "no error message available";
+        if (!is_token_related)
+            await this.token_promise.catch(() => this.token_promise = new Promise(r => r));
+        let url = `${this.server}`;
+        if (url.slice(-1) !== "/")
+            url += "/";
+        url += endpoint.join("/");
+        if (method === "get" && parameters) { // for GET requests specifically, requests need to be shaped in very particular ways
+            url += "?" + (Object.entries(adaptParametersForGETRequests(parameters)).map((param) => {
+                if (!Array.isArray(param[1])) {
+                    return `${param[0]}=${param[1]}`;
+                }
+                return param[1].map((array_element) => `${param[0]}=${array_element}`).join("&");
+            }).join("&"));
+        }
+        const signals = [];
+        if (this.timeout > 0)
+            signals.push(AbortSignal.timeout(this.timeout * 1000));
+        if (this.signal && !is_token_related)
+            signals.push(this.signal);
+        const response = await fetch(url, {
+            method,
+            headers: {
+                "Authorization": is_token_related ? undefined : `${this.token_type} ${this.token}`,
+                ...this.headers
+            },
+            body: method !== "get" ? JSON.stringify(parameters) : undefined, // parameters are here if method is NOT GET
+            signal: AbortSignal.any(signals)
+        })
+            .catch((error) => {
+            if (error.name === "TimeoutError" && this.retry_on_timeout)
+                to_retry = true;
+            this.log(true, error.message);
+            error_object = error;
+            error_message = `${error.name} (${error.message ?? error.errno ?? error.type})`;
+        })
+            .finally(() => this.number_of_requests += 1);
+        const request_id = `(${String(this.number_of_requests).padStart(8, "0")})`;
+        if (response) {
+            if (parameters.password)
+                parameters.password = "<REDACTED>";
+            this.log(this.verbose !== "none" && !response.ok, response.statusText, response.status, { method, endpoint, parameters }, request_id);
+            if (!response.ok) {
+                error_code = response.status;
+                error_message = response.statusText;
+                if (this.retry_on_status_codes.includes(response.status))
+                    to_retry = true;
+                if (!is_token_related) {
+                    if (response.status === 401) {
+                        if (this.set_token_on_401 && !info.has_new_token) {
+                            if (!this.is_setting_token) {
+                                this.log(true, "Your token might have expired, I will attempt to get a new token...", request_id);
+                                if (await this.setNewToken() && this.retry_on_new_token) {
+                                    to_retry = true;
+                                    info.has_new_token = true;
+                                }
+                            }
+                            else {
+                                this.log(true, "A new token is currently being obtained!", request_id);
+                                if (this.retry_on_new_token) {
+                                    to_retry = true;
+                                    info.has_new_token = true;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        if (to_retry === true && info.number_try <= this.retry_maximum_amount) {
+            this.log(true, `Will request again in ${this.retry_delay} seconds...`, `(retry #${info.number_try}/${this.retry_maximum_amount})`, request_id);
+            await new Promise(res => setTimeout(res, this.retry_delay * 1000));
+            return await this.fetch(is_token_related, method, endpoint, parameters, { number_try: info.number_try + 1, has_new_token: info.has_new_token });
+        }
+        if (!response || !response.ok) {
+            throw new APIError(error_message, this.server, method, endpoint, parameters, error_code, error_object);
+        }
+        return response;
+    }
+    /**
+     * The function that directly communicates with the API! Almost every functions of the API object uses this function!
+     * @param method The type of request, each endpoint uses a specific one (if it uses multiple, the intent and parameters become different)
+     * @param endpoint What comes in the URL after `api/`, **DO NOT USE TEMPLATE LITERALS (\`) OR THE ADDITION OPERATOR (+), put everything separately for type safety**
+     * @param parameters The things to specify in the request, such as the beatmap_id when looking for a beatmap
+     * @param settings Additional settings **to add** to the current settings of the `fetch()` request
+     * @returns A Promise with the API's response
+     */
+    async request(method, endpoint, parameters = {}) {
+        try {
+            const response = await this.fetch(false, method, endpoint, parameters);
+            if (response.status === 204)
+                return undefined; // 204 means the request worked as intended and did not give us anything, so just return nothing
+            const arrBuff = await response.arrayBuffer();
+            const buff = Buffer.from(arrBuff);
+            try { // Assume the response is in JSON format as it often is, it'll fail into the catch block if it isn't anyway
+                // My thorough testing leads me to believe nothing would change if the encoding was also "binary" here btw
+                return correctType(JSON.parse(buff.toString("utf-8")));
+            }
+            catch { // Assume the response is supposed to not be in JSON format so return it as simple text
+                return buff.toString("binary");
+            }
+        }
+        catch (e) {
+            if (e instanceof APIError)
+                throw e;
+            // Manual testing leads me to believe a TimeoutError is possible after the request ended (while arrayBuffer() is going on, presumably)
+            // Still no matter the Error, we want an APIError
+            throw new APIError(`${e?.name} (${e?.message ?? e?.errno ?? e?.type})`, this.server, method, endpoint, parameters, undefined, e);
+        }
+    }
+    async getWebsiteStats(website_id, startAt, endAt) {
+        return await this.request("get", ["websites", website_id, "stats"], { startAt: Number(startAt), endAt: Number(endAt) });
+    }
+}

package/dist/utilities.d.ts

@@ -0,0 +1,17 @@
+/**
+ * When using `fetch()` for a GET request, you can't just give the parameters the same way you'd give them for a POST request!
+ * @param parameters The parameters as they'd be for a POST request (prior to using `JSON.stringify`)
+ * @returns Parameters adapted for a GET request
+ */
+export declare function adaptParametersForGETRequests(parameters: {
+    [k: string]: any;
+}): {
+    [k: string]: any;
+};
+/**
+ * Some stuff doesn't have the right type to begin with, such as dates, which are being returned as strings, this fixes that
+ * @param x Anything, but should be a string, an array that contains a string, or an object which has a string
+ * @param force_string Should `x` be as much as a string as it can? (defaults to false)
+ * @returns x, but with it (or what it contains) now having the correct type
+ */
+export declare function correctType(x: any, force_string?: boolean): any;

package/dist/utilities.js

@@ -0,0 +1,82 @@
+// This file hosts important functions that are too big or unreadable to belong in another file
+/**
+ * When using `fetch()` for a GET request, you can't just give the parameters the same way you'd give them for a POST request!
+ * @param parameters The parameters as they'd be for a POST request (prior to using `JSON.stringify`)
+ * @returns Parameters adapted for a GET request
+ */
+export function adaptParametersForGETRequests(parameters) {
+    // If a parameter is an empty string or is undefined, remove it
+    Object.entries(parameters).forEach(([key, value]) => {
+        if (!String(value).length || value === undefined) {
+            delete parameters[key];
+        }
+    });
+    // If a parameter is an Array, add "[]" to its name, so the server understands the request properly
+    Object.entries(parameters).forEach(([key, value]) => {
+        if (Array.isArray(value) && !key.includes("[]")) {
+            parameters[`${key}[]`] = value;
+            delete parameters[key];
+        }
+    });
+    // If a parameter is an object, add its properties in "[]" such as "cursor[id]=5&cursor[score]=36.234"
+    const parameters_to_add = {};
+    Object.entries(parameters).forEach(([key, value]) => {
+        if (typeof value === "object" && !Array.isArray(value) && value !== null) {
+            Object.entries(value).forEach(([key2, value2]) => {
+                parameters_to_add[`${key}[${key2}]`] = value2;
+            });
+            delete parameters[key];
+        }
+    });
+    Object.entries(parameters_to_add).forEach(([key, value]) => {
+        parameters[key] = value;
+    });
+    // If a parameter is a date, make it a string
+    Object.entries(parameters).forEach(([key, value]) => {
+        if (value instanceof Date) {
+            parameters[key] = value.toISOString();
+        }
+    });
+    return parameters;
+}
+/**
+ * Some stuff doesn't have the right type to begin with, such as dates, which are being returned as strings, this fixes that
+ * @param x Anything, but should be a string, an array that contains a string, or an object which has a string
+ * @param force_string Should `x` be as much as a string as it can? (defaults to false)
+ * @returns x, but with it (or what it contains) now having the correct type
+ */
+export function correctType(x, force_string) {
+    // Apply this very function to all elements of the array, with `force_string` on if previously turned on
+    if (Array.isArray(x)) {
+        return x.map((e) => correctType(e, force_string));
+    }
+    // Objects have depth, we need to run this very function on all of their values
+    if (typeof x === "object" && x !== null) {
+        const keys = Object.keys(x);
+        const vals = Object.values(x);
+        // If a key is any of those, the value is expected to be a string, so we use `force_string` to make correctType convert them to string for us
+        const unconvertables = [];
+        for (let i = 0; i < keys.length; i++) {
+            x[keys[i]] = correctType(vals[i], unconvertables.some((p) => keys[i] === p));
+        }
+        return x;
+    }
+    // If `force_string` is on and is applicable, convert to a string (even if already string)
+    if (force_string && typeof x !== "object") {
+        return String(x);
+    }
+    // Responses by the API have their dates as strings in different formats, convert those strings to Date objects
+    if (/^[+-[0-9][0-9]+-[0-9]{2}-[0-9]{2}($|[ T].*)/.test(x)) {
+        // Before converting, force all dates into UTC+0 (to avoid differences depending of which timezone you run `new Date()` in)
+        if (/[0-9]{2}:[0-9]{2}:[0-9]{2}$/.test(x))
+            x += "Z";
+        if (/[0-9]{2}:[0-9]{2}:[0-9]{2}\+[0-9]{2}:[0-9]{2}$/.test(x))
+            x = x.substring(0, x.indexOf("+")) + "Z";
+        return new Date(x);
+    }
+    // If the string can be converted to a number and isn't `force_string`ed, convert it (namely because of user cover id and few others)
+    if (!isNaN(x) && x !== "" && x !== null && typeof x !== "boolean") {
+        return Number(x);
+    }
+    return x;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "umami-api-js",
+  "version": "0.0.1",
+  "description": "Package to easily access the umami api!",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "prepublish": "npm run build",
+    "build": "tsc",
+    "test": "npm run build && node ./dist/test.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "Taevas",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/Taevas/umami-api-js"
+  },
+  "homepage": "https://codeberg.org/Taevas/umami-api-js",
+  "keywords": [
+    "umami",
+    "api",
+    "wrapper",
+    "api-wrapper"
+  ],
+  "license": "Unlicense",
+  "devDependencies": {
+    "@types/chai": "^5.2.2",
+    "@types/node": "^24.3.1",
+    "dotenv": "^17.2.2",
+    "typescript": "^5.9.2"
+  }
+}