umami-api-js 0.2.2 → 1.0.1

package/README.md

@@ -1,13 +1,15 @@
 # umami-api-js
 
+[![release](https://codeberg.org/Taevas/umami-api-js/badges/release.svg)](https://codeberg.org/Taevas/umami-api-js/releases)
+[![automated testing](https://codeberg.org/Taevas/umami-api-js/badges/workflows/test.yml/badge.svg)](https://codeberg.org/Taevas/umami-api-js/actions?workflow=test.yml)
 [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/V7V4J78L0)
 
 A package to interact with [the API of **self-hosted instances** of Umami](https://umami.is/docs/api).
 
-It has not been tested on [Umami Cloud](https://umami.is/docs/cloud) (the instance of Umami hosted by its creators) and is therefore not expected to work there.
-
 The documentation for the latest version of this package can be found at any time on [umami-api-js.taevas.xyz](https://umami-api-js.taevas.xyz)!
 
+Please note: It has not been made to work on [Umami Cloud](https://umami.is/docs/cloud) (the instance of Umami hosted by its creators) and is therefore not expected to work there.
+
 ## How to install and get started
 
 Before installing, if using Node.js, check if you're running version 20 or above:
@@ -29,19 +31,97 @@ Finally, you will want to create an API object, which you will use for essential
 
 ```typescript
 // TypeScript
-import * as umami from "umami-api-js"
+import * as umami from "umami-api-js";
 
 // The API of self-hosted Umami instances authenticates with the credentials of actual accounts
-const api = new umami.API("https://visitors.taevas.xyz/api", "<username>", "<password>") // first argument being the API route of a self-hosted Umami instance
+const api = new umami.API(
+  "https://visitors.taevas.xyz/api",
+  "<username>",
+  "<password>",
+); // first argument being the API route of a self-hosted Umami instance
 
 // The website_id is featured in multiple places, like where you'd see the analytics script or the settings interface
 async function displayStats(website_id: string) {
   const now = new Date();
   const sevendaysago = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
-  const stats = await api.getWebsiteStats(website_id, {startAt: sevendaysago, endAt: now, timezone: "UTC"});
+  const stats = await api.getWebsiteStats(website_id, {
+    startAt: sevendaysago,
+    endAt: now,
+    timezone: "UTC",
+  });
 
-  console.log(`This website recently had ${stats.visits} visits from ${stats.visitors} visitors!`);
+  console.log(
+    `This website recently had ${stats.visits} visits from ${stats.visitors} visitors!`,
+  );
 }
 
 displayStats("f196d626-e609-4841-9a80-0dc60f523ed5");
 ```
+
+### Configuration options
+
+Your [`api`](https://umami-api-js.taevas.xyz/classes/API.html) object has many properties (listed as _Accessors_ in the documentation) which you can modify in order to change its behaviour. There are two ways to do that, the first of which is to do it at any point after you've created your object:
+
+```typescript
+const api = new umami.API("<api_endpoint>", "<username>", "<password>");
+// Log all requests made by this api object
+api.verbose = "all";
+// Change the amount of seconds it takes for requests to timeout
+api.timeout = 10;
+```
+
+The other way would be at the same time you're creating your `api` object, like that:
+
+```typescript
+// Same as above, in one line as the api object gets created
+const api = new umami.API("<api_endpoint>", "<username>", "<password>", {
+  verbose: "all",
+  timeout: 10,
+});
+```
+
+### Tokens
+
+An [`access_token`](https://umami-api-js.taevas.xyz/classes/API.html#access_token) is required to access the API. When you first create your [`api`](https://umami-api-js.taevas.xyz/classes/API.html) object, that token is automatically set before any request is made, so you don't have to worry about that!
+
+Unlike many other web applications, [Umami doesn't expire tokens after a certain amount of time](https://github.com/umami-software/umami/discussions/1170), meaning in theory that you would only ever need to request a new token if your credentials change. After changing the [username](https://umami-api-js.taevas.xyz/classes/API.html#username) or [password](https://umami-api-js.taevas.xyz/classes/API.html#password), you may manually call [`setNewToken()`](https://umami-api-js.taevas.xyz/classes/API.html#setnewtoken), which will replace your previous token with a new one!
+
+This package was built with the expectation that tokens would eventually expire, so you've got some configuration options you can play around with:
+
+- Keep the [`set_token_on_expires`](https://umami-api-js.taevas.xyz/classes/API.html#set_token_on_expires) option to true if you'd like the object to call `setNewToken()` automatically as soon as the token expires
+- By default, the [`set_token_on_401`](https://umami-api-js.taevas.xyz/classes/API.html#set_token_on_401) option is set to false, which (as its name indicates) would do that upon encountering a 401
+- When that happens, if [`retry_on_new_token`](https://umami-api-js.taevas.xyz/classes/API.html#retry_on_new_token) is set to true as it is by default, it will retry the request it has encountered a 401 on, with the new token! (note that loops are prevented, it won't retry or get another token if the same request with the new token gets a 401)
+
+At any point in time, you can see when the current `access_token` is set to expire through the [`expires`](https://umami-api-js.taevas.xyz/classes/API.html#expires) property of the API.
+
+### Retries
+
+Your `api` object has a configurable behaviour when it comes to handling requests that have failed for certain reasons. It may "retry" a request, meaning **not throwing and making the request again as if it hasn't failed** under the following circumstances:
+
+NOTE: [`retry_maximum_amount`](https://umami-api-js.taevas.xyz/classes/API.html#retry_maximum_amount) must be above 0 for any retry to happen in the first place!
+
+- [`set_token_on_401`](https://umami-api-js.taevas.xyz/classes/API.html#set_token_on_401) is set, a token is obtained thanks to it, and [`retry_on_new_token`](https://umami-api-js.taevas.xyz/classes/API.html#retry_on_new_token) is also set
+- A failed request has a status code featured in [`retry_on_status_codes`](https://umami-api-js.taevas.xyz/classes/API.html#retry_on_status_codes)
+- [`retry_on_timeout`](https://umami-api-js.taevas.xyz/classes/API.html#retry_on_timeout) is set and a timeout has happened
+
+You can further configure retries through [`retry_delay`](https://umami-api-js.taevas.xyz/classes/API.html#retry_delay) and the aforementioned `retry_maximum_amount`.
+
+### Calling the functions, but literally
+
+This package's functions can be accessed both through the api object and through namespaces! It essentially means that for convenience's sake, there are two ways to do anything:
+
+```typescript
+// Obtaining a match, assuming an `api` object already exists and everything from the package is imported as `umami`
+const team_1 = await api.getTeam("<team_id>"); // through the api object
+const team_2 = await umami.Teams.get_TEAMID.call(api, "<team_id>"); // through the namespaces
+// `team_1` and `team_2` are the same, because they're essentially using the same function!
+
+// The same, but for obtaining the authenticated user
+const me_1 = await api.getMyself();
+const me_2 = await umami.Me.get.call(api);
+// `me_1` and `me_2` are also the same!
+```
+
+As you may have noticed, when calling the functions through the namespaces, instead of doing something like `get()`, we instead do `get.call()` and use [the call() method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call) in order to provide a `this` value; the api object!
+
+Of course, using [the apply() method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply) would also work, so just do things the way you prefer or the way that is more intuitive to you!

package/dist/index.d.ts

@@ -10,7 +10,7 @@ import { Teams } from "./namespaces/Teams.js";
 import { Users } from "./namespaces/Users.js";
 import { Websites } from "./namespaces/Websites.js";
 import { WebsiteStats } from "./namespaces/WebsiteStats.js";
-export { Admin, Events, Links, Me, Pixels, Websites, WebsiteStats, Realtime, Reports, Sessions, Teams, Users };
+export { Admin, Events, Links, Me, Pixels, Websites, WebsiteStats, Realtime, Reports, Sessions, Teams, Users, };
 export interface DeletionResult {
     ok: boolean;
 }
@@ -114,7 +114,7 @@ export declare class API {
      * @param username The username of the user you're logging in as
      * @param password The password of the user you're logging in as
      * @param settings Additional settings you'd like to specify now rather than later, check out the Accessors at https://umami-api-js.taevas.xyz/classes/API.html
-    */
+     */
     static createAsync(server: API["server"], username: API["username"], password: API["password"], settings?: Partial<API>): Promise<API>;
     private _token;
     /** The key that allows you to talk with the API */
@@ -125,9 +125,13 @@ export declare class API {
     get token_type(): string;
     set token_type(token: string);
     private _expires;
-    /** The expiration date of your token */
-    get expires(): Date;
-    set expires(date: Date);
+    /**
+     * The expiration date of your token
+     * @remarks Umami v3.0.3 behaviour is to NOT expire tokens a given amount of time after creation,
+     * see https://github.com/umami-software/umami/discussions/1170
+     */
+    get expires(): Date | null;
+    set expires(date: Date | null);
     private _server;
     /** The base URL where requests should land, **should include the `/api` portion if applicable** */
     get server(): string;
@@ -171,7 +175,7 @@ export declare class API {
     get set_token_on_creation(): boolean;
     set set_token_on_creation(bool: 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**) */
+    /** If true, upon failing a request due to a 401, it will call {@link API.setNewToken} (defaults to **false**) */
     get set_token_on_401(): boolean;
     set set_token_on_401(bool: boolean);
     private _set_token_on_expires;

package/dist/index.js

@@ -11,7 +11,7 @@ import { Users } from "./namespaces/Users.js";
 import { Websites } from "./namespaces/Websites.js";
 import { WebsiteStats } from "./namespaces/WebsiteStats.js";
 import { adaptParametersForGETRequests, correctType } from "./utilities.js";
-export { Admin, Events, Links, Me, Pixels, Websites, WebsiteStats, Realtime, Reports, Sessions, Teams, Users };
+export { Admin, Events, Links, Me, Pixels, Websites, WebsiteStats, Realtime, Reports, Sessions, Teams, Users, };
 /** If the {@link API} throws an error, it should always be an {@link APIError}! */
 export class APIError extends Error {
     message;
@@ -47,22 +47,32 @@ export class APIError extends Error {
 /** An API instance is needed to make requests to the server! */
 export class API {
     constructor(server_or_settings, username, password, settings) {
-        settings ??= typeof server_or_settings !== "string" ? server_or_settings : undefined;
+        settings ??=
+            typeof server_or_settings !== "string" ? server_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] : {};
+                settings[key] === undefined
+                    ? delete settings[key]
+                    : {};
             });
             Object.assign(this, settings);
         }
-        if (this.is_setting_token) { // Very likely a clone created while the original didn't have a valid token
+        if (this.is_setting_token) {
+            // Very likely a clone created while the original didn't have a valid token
             this.set_token_on_expires = false; // In which case allow the clone to get its own token, but not renewing it automatically
         } // And if the clone keeps getting used, `set_token_on_401` being true should cover that
-        /** We want to set a new token instantly if account credentials have been provided */
-        if (this.set_token_on_creation && typeof server_or_settings === "string" && username && password) {
-            this.server = server_or_settings;
+        if (username) {
             this.username = username;
+        }
+        if (password) {
             this.password = password;
+        }
+        if (typeof server_or_settings === "string") {
+            this.server = server_or_settings;
+        }
+        /** We want to set a new token instantly if account credentials have been provided */
+        if (this.set_token_on_creation && username && password) {
             this.setNewToken();
         }
     }
@@ -73,7 +83,7 @@ export class API {
      * @param username The username of the user you're logging in as
      * @param password The password of the user you're logging in as
      * @param settings Additional settings you'd like to specify now rather than later, check out the Accessors at https://umami-api-js.taevas.xyz/classes/API.html
-    */
+     */
     static async createAsync(server, username, password, settings) {
         // We don't want `new API` to set the token, as we can't await it (and awaiting `token_promise` sounds like a bad idea)
         if (settings) {
@@ -89,15 +99,29 @@ export class API {
     }
     _token = "";
     /** The key that allows you to talk with the API */
-    get token() { return this._token; }
-    set token(token) { this._token = token; }
+    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 setNewToken anyway
-    /** The expiration date of your token */
-    get expires() { return this._expires; }
+    get token_type() {
+        return this._token_type;
+    }
+    set token_type(token) {
+        this._token_type = token;
+    }
+    _expires = null;
+    /**
+     * The expiration date of your token
+     * @remarks Umami v3.0.3 behaviour is to NOT expire tokens a given amount of time after creation,
+     * see https://github.com/umami-software/umami/discussions/1170
+     */
+    get expires() {
+        return this._expires;
+    }
     set expires(date) {
         this._expires = date;
         this.updateTokenTimer();
@@ -105,18 +129,30 @@ export class API {
     // CLIENT INFO
     _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; }
+    get server() {
+        return this._server;
+    }
+    set server(server) {
+        this._server = server;
+    }
     _username = "";
     /** The username of the account */
-    get username() { return this._username; }
-    set username(username) { this._username = username; }
+    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; }
+    get password() {
+        return this._password;
+    }
+    set password(password) {
+        this._password = password;
+    }
     _headers = {
-        "Accept": "application/json",
+        Accept: "application/json",
         "Accept-Encoding": "gzip",
         "Content-Type": "application/json",
         "User-Agent": "umami-api-js (codeberg.org/Taevas/umami-api-js)",
@@ -125,8 +161,12 @@ export class API {
      * Used in practically all requests, those are all the headers the package uses excluding `Authorization`, the one with the token
      * @remarks If the User-Agent is not liked by https://isbot.js.org/, Umami might give responses akin to `{beep: "boop"}`
      */
-    get headers() { return this._headers; }
-    set headers(headers) { this._headers = headers; }
+    get headers() {
+        return this._headers;
+    }
+    set headers(headers) {
+        this._headers = headers;
+    }
     _user = {
         id: "",
         username: "",
@@ -135,14 +175,20 @@ export class API {
         isAdmin: false,
     };
     /** Information about the account that has been used to log in */
-    get user() { return this._user; }
-    set user(user) { this._user = user; }
+    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);
+    token_promise = new Promise((r) => {
+        r();
+    }); // `{r()}` over `r` prevents Node.js weirdness when awaited
     /**
      * This contacts the server in order to get and set a new {@link API.token}!
      * @remarks The API object requires a {@link API.username} and a {@link API.password} to successfully get any token
@@ -158,8 +204,7 @@ export class API {
         this.token_promise = new Promise((resolve, reject) => {
             this.fetch(true, "post", ["auth", "login"], body)
                 .then((response) => {
-                response.json()
-                    .then((json) => {
+                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);
@@ -168,9 +213,10 @@ export class API {
                     // Note: `json` currently only has `token` & `user`
                     this.token = json.token;
                     this.user = json.user;
-                    const expiration_date = new Date();
-                    expiration_date.setDate(expiration_date.getDate() + 1); // Assume 24 hours
-                    this.expires = expiration_date;
+                    // If Umami ever sets expiration dates on tokens, the code to let the API object know should be here
+                    // const expiration_date = new Date();
+                    // expiration_date.setDate(expiration_date.getDate() + 1); // Assume 24 hours
+                    // this.expires = expiration_date;
                     resolve();
                 });
             })
@@ -184,24 +230,36 @@ export class API {
     }
     _set_token_on_creation = true;
     /** If true, when creating your API object, a call to {@link API.setNewToken} will be automatically made (defaults to **true**) */
-    get set_token_on_creation() { return this._set_token_on_creation; }
-    set set_token_on_creation(bool) { this._set_token_on_creation = bool; }
-    _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; }
+    get set_token_on_creation() {
+        return this._set_token_on_creation;
+    }
+    set set_token_on_creation(bool) {
+        this._set_token_on_creation = bool;
+    }
+    _set_token_on_401 = false;
+    /** If true, upon failing a request due to a 401, it will call {@link API.setNewToken} (defaults to **false**) */
+    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; }
+    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; }
+    get token_timer() {
+        return this._token_timer;
+    }
     set token_timer(timer) {
         // if a previous one already exists, clear it
         if (this._token_timer) {
@@ -238,43 +296,75 @@ export class API {
     // CLIENT CONFIGURATION
     _verbose = "none";
     /** Which events should be logged (defaults to **none**) */
-    get verbose() { return this._verbose; }
-    set verbose(verbose) { this._verbose = verbose; }
+    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; }
+    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; }
+    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; }
+    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; }
+    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; }
+    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; }
+    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; }
+    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
@@ -298,27 +388,45 @@ export class API {
      * @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 }) {
+    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));
+            await this.token_promise.catch(() => (this.token_promise = new Promise((r) => {
+                r();
+            })));
         for (const [p, v] of Object.entries(parameters)) {
-            parameters[p] = v instanceof Date ? Number(v) : v; // Convert Dates to ms
+            // Convert Dates to ms
+            if (typeof v === "object" && !Array.isArray(v) && v !== null) {
+                // It's frankly unnecessary to have better-written code
+                for (const [p2, v2] of Object.entries(v)) {
+                    parameters[p][p2] = v2 instanceof Date ? Number(v2) : v2;
+                }
+            }
+            parameters[p] = v instanceof Date ? Number(v) : v;
         }
         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("&"));
+        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)
@@ -328,11 +436,13 @@ export class API {
         const response = await fetch(url, {
             method,
             headers: {
-                "Authorization": is_token_related ? undefined : `${this.token_type} ${this.token}`,
-                ...this.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)
+            signal: AbortSignal.any(signals),
         })
             .catch((error) => {
             if (error.name === "TimeoutError" && this.retry_on_timeout)
@@ -341,14 +451,13 @@ export class API {
             error_object = error;
             error_message = `${error.name} (${error.message ?? error.errno ?? error.type})`;
         })
-            .finally(() => this.number_of_requests += 1);
+            .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;
@@ -357,7 +466,7 @@ export class API {
                         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) {
+                                if ((await this.setNewToken()) && this.retry_on_new_token) {
                                     to_retry = true;
                                     info.has_new_token = true;
                                 }
@@ -376,14 +485,19 @@ export class API {
         }
         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 });
+            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) {
-            const resp = response ? {
-                status_code: response.status,
-                json: await response.json()
-            } : undefined;
+            const resp = response
+                ? {
+                    status_code: response.status,
+                    json: await response.json(),
+                }
+                : undefined;
             throw new APIError(error_message, this.server, method, endpoint, parameters, resp, error_object);
         }
         return response;
@@ -402,11 +516,13 @@ export class API {
                 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
+            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
+            catch {
+                // Assume the response is supposed to not be in JSON format so return it as simple text
                 return buff.toString("binary");
             }
         }
@@ -424,7 +540,10 @@ export class API {
      * @group Sending stats
      */
     async sendStats(websiteId, payload, type = "event") {
-        return await this.request("post", ["send"], { payload: { website: websiteId, ...payload }, type });
+        return await this.request("post", ["send"], {
+            payload: { website: websiteId, ...payload },
+            type,
+        });
     }
     // ADMIN
     /** @group Admin endpoints */

package/dist/namespaces/Events.js

@@ -9,7 +9,12 @@ export var Events;
     Events.get_WEBSITEID_Events = get_WEBSITEID_Events;
     /** Gets event-data for a individual event: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-dataeventid */
     async function get_WEBSITEID_Eventdata_EVENTID(websiteId, eventId) {
-        return await this.request("get", ["websites", websiteId, "event-data", eventId]);
+        return await this.request("get", [
+            "websites",
+            websiteId,
+            "event-data",
+            eventId,
+        ]);
     }
     Events.get_WEBSITEID_Eventdata_EVENTID = get_WEBSITEID_Eventdata_EVENTID;
     /**

package/dist/namespaces/Reports.d.ts

@@ -23,7 +23,7 @@ export declare namespace Reports {
         endDate: Date | number;
     }
     type ReportType = "attribution" | "breakdown" | "funnel" | "goal" | "journey" | "retention" | "revenue" | "utm";
-    /** Get all reports by website ID: https://umami.is/docs/api/reports#get-apireports (TODO UNTESTED) */
+    /** Get all reports by website ID: https://umami.is/docs/api/reports#get-apireports */
     function get(this: API, websiteId: Websites.Website["id"], parameters: {
         type: ReportType;
     } & Omit<GenericRequestParameters, "search">): Promise<Report[]>;
@@ -43,15 +43,15 @@ export declare namespace Reports {
     /** Updates a report: https://umami.is/docs/api/reports#post-apireportsreportid */
     function post_REPORTID(this: API, reportId: Report["id"], parameters?: {
         /** Your website id */
-        websiteId?: Websites.Website["id"];
+        websiteId: Websites.Website["id"];
         /** Report type */
-        type?: ReportType;
+        type: ReportType;
         /** Name of report */
         name?: Report["name"];
         /** Description of report */
         description?: Report["description"];
         /** Parameters for report */
-        parameters?: Report["parameters"];
+        parameters: Report["parameters"];
     }): Promise<Report>;
     /** Deletes a report: https://umami.is/docs/api/reports#delete-apireportsreportid */
     function delete_REPORTID(this: API, reportId: Report["id"]): Promise<DeletionResult>;
@@ -121,7 +121,10 @@ export declare namespace Reports {
         num: number;
         total: number;
     }
-    /** Track your goals for pageviews and events: https://umami.is/docs/api/reports#post-apireportsgoals (TODO UNTESTED) */
+    /**
+     * Track your goals for pageviews and events: https://umami.is/docs/api/reports#post-apireportsgoals
+     * @remarks Here be dragons: I have no idea how to use this endpoint without it returning a client/server error, my apologies - The package developer
+     */
     function postGoals(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
         /** Can accept filter parameters */
         filters?: Filters;
@@ -129,6 +132,12 @@ export declare namespace Reports {
         type: "path" | "event";
         /** Conversion step value */
         value: string;
+        /** Undocumented */
+        operator?: "count" | "sum" | "average";
+        /** Undocumented */
+        property?: string;
+        /** Undocumented */
+        name?: string;
     }): Promise<Goals>;
     interface Journey {
         items: (string | null)[];

package/dist/namespaces/Reports.js

@@ -1,15 +1,21 @@
 /** Using reports throught [sic] the api: https://umami.is/docs/api/reports */
 export var Reports;
 (function (Reports) {
-    /** Get all reports by website ID: https://umami.is/docs/api/reports#get-apireports (TODO UNTESTED) */
+    /** Get all reports by website ID: https://umami.is/docs/api/reports#get-apireports */
     async function get(websiteId, parameters) {
-        const response = await this.request("get", ["reports"], { websiteId, ...parameters });
+        const response = await this.request("get", ["reports"], {
+            websiteId,
+            ...parameters,
+        });
         return response.data;
     }
     Reports.get = get;
     /** Creates a report: https://umami.is/docs/api/reports#post-apireports */
     async function post(websiteId, parameters) {
-        return await this.request("post", ["reports"], { websiteId, ...parameters });
+        return await this.request("post", ["reports"], {
+            websiteId,
+            ...parameters,
+        });
     }
     Reports.post = post;
     /** Gets a report by ID: https://umami.is/docs/api/reports#get-apireportsreportid */
@@ -19,7 +25,7 @@ export var Reports;
     Reports.get_REPORTID = get_REPORTID;
     /** Updates a report: https://umami.is/docs/api/reports#post-apireportsreportid */
     async function post_REPORTID(reportId, parameters) {
-        return await this.request("get", ["reports", reportId], parameters);
+        return await this.request("post", ["reports", reportId], parameters);
     }
     Reports.post_REPORTID = post_REPORTID;
     /** Deletes a report: https://umami.is/docs/api/reports#delete-apireportsreportid */
@@ -28,9 +34,15 @@ export var Reports;
     }
     Reports.delete_REPORTID = delete_REPORTID;
     /** Private function to deal more easily with the post functions that don't involve actual reports */
-    async function postNonReports(api, type, websiteId, filters, parameters) {
+    async function postNonReports(api, type, websiteId, filters, parameters, name) {
         const endpoint = type === "goal" ? "goals" : type; // so close yet so far away from clean code
-        return await api.request("post", ["reports", endpoint], { websiteId, type, filters: filters ?? {}, parameters });
+        return await api.request("post", ["reports", endpoint], {
+            websiteId,
+            type,
+            filters: filters ?? {},
+            name,
+            parameters,
+        });
     }
     /** See how users engage with your marketing and what drives conversions: https://umami.is/docs/api/reports#post-apireportsattribution */
     async function postAttribution(websiteId, parameters) {
@@ -62,14 +74,17 @@ export var Reports;
         });
     }
     Reports.postFunnel = postFunnel;
-    /** Track your goals for pageviews and events: https://umami.is/docs/api/reports#post-apireportsgoals (TODO UNTESTED) */
+    /**
+     * Track your goals for pageviews and events: https://umami.is/docs/api/reports#post-apireportsgoals
+     * @remarks Here be dragons: I have no idea how to use this endpoint without it returning a client/server error, my apologies - The package developer
+     */
     async function postGoals(websiteId, parameters) {
         return await postNonReports(this, "goal", websiteId, parameters.filters, {
             startDate: parameters.startDate,
             endDate: parameters.endDate,
             type: parameters.type,
             value: parameters.value,
-        });
+        }, parameters.name);
     }
     Reports.postGoals = postGoals;
     /** Understand how users nagivate [sic] through your website: https://umami.is/docs/api/reports#post-apireportsjourney */

package/dist/namespaces/Sessions.js

@@ -10,7 +10,9 @@ export var Sessions;
     /** Gets summarized website session statistics: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessionsstats */
     async function get_WEBSITEID_SessionsStats(websiteId, parameters) {
         const response = await this.request("get", ["websites", websiteId, "sessions", "stats"], parameters);
-        Object.values(response).forEach((v) => { v.value = Number(v.value); });
+        Object.values(response).forEach((v) => {
+            v.value = Number(v.value);
+        });
         return response;
     }
     Sessions.get_WEBSITEID_SessionsStats = get_WEBSITEID_SessionsStats;
@@ -21,7 +23,12 @@ export var Sessions;
     Sessions.get_WEBSITEID_SessionsWeekly = get_WEBSITEID_SessionsWeekly;
     /** Gets session details for a individual session: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessionssessionid */
     async function get_WEBSITEID_Sessions_SESSIONID(websiteId, sessionId) {
-        return await this.request("get", ["websites", websiteId, "sessions", sessionId]);
+        return await this.request("get", [
+            "websites",
+            websiteId,
+            "sessions",
+            sessionId,
+        ]);
     }
     Sessions.get_WEBSITEID_Sessions_SESSIONID = get_WEBSITEID_Sessions_SESSIONID;
     /** Gets session activity for a individual session: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessionssessionidactivity */
@@ -31,7 +38,13 @@ export var Sessions;
     Sessions.get_WEBSITEID_Sessions_SESSIONID_Activity = get_WEBSITEID_Sessions_SESSIONID_Activity;
     /** Gets session properties for a individual session: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessionssessionidproperties */
     async function get_WEBSITEID_Sessions_SESSIONID_Properties(websiteId, sessionId) {
-        return await this.request("get", ["websites", websiteId, "sessions", sessionId, "properties"]);
+        return await this.request("get", [
+            "websites",
+            websiteId,
+            "sessions",
+            sessionId,
+            "properties",
+        ]);
     }
     Sessions.get_WEBSITEID_Sessions_SESSIONID_Properties = get_WEBSITEID_Sessions_SESSIONID_Properties;
     /** Gets session data counts by property name: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-dataproperties */

package/dist/namespaces/Teams.js

@@ -53,7 +53,9 @@ export var Teams;
     Teams.get_TEAMID_Users_USERID = get_TEAMID_Users_USERID;
     /** Update a user's role on a team: https://umami.is/docs/api/teams#post-apiteamsteamidusersuserid */
     async function post_TEAMID_Users_USERID(teamId, userId, role) {
-        return await this.request("post", ["teams", teamId, "users", userId], { role });
+        return await this.request("post", ["teams", teamId, "users", userId], {
+            role,
+        });
     }
     Teams.post_TEAMID_Users_USERID = post_TEAMID_Users_USERID;
     /** Remove a user from a team: https://umami.is/docs/api/teams#delete-apiteamsteamidusersuserid */

package/dist/utilities.js

@@ -56,9 +56,10 @@ export function correctType(x, force_string) {
         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 = ["value"];
-        const unconvertables_substrings = ["string", "name", "Id"]; // or if the key contains any of those substrings
+        const unconvertables_substrings = ["string", "name", "id"]; // or if the key contains any of those substrings
         for (let i = 0; i < keys.length; i++) {
-            x[keys[i]] = correctType(vals[i], unconvertables.some((u) => keys[i] === u) || unconvertables_substrings.some((s) => keys[i].toLowerCase().includes(s)));
+            x[keys[i]] = correctType(vals[i], unconvertables.some((u) => keys[i] === u) ||
+                unconvertables_substrings.some((s) => keys[i].toLowerCase().includes(s)));
         }
         return x;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umami-api-js",
-  "version": "0.2.2",
+  "version": "1.0.1",
   "description": "Package to easily access the Umami api!",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,7 @@
   "scripts": {
     "prepublish": "npm run build",
     "build": "tsc",
+    "prettier": "prettier . --write",
     "test": "npm run build && node ./dist/test.js",
     "docs": "npx typedoc lib/index.ts --cname umami-api-js.taevas.xyz --plugin ./docs_plugins/visitors.ts"
   },
@@ -31,11 +32,12 @@
   "devDependencies": {
     "@types/chai": "^5.2.3",
     "@types/node": "^24.9.2",
-    "ajv": "^8.17.1",
+    "ajv": "^8.18.0",
     "chai": "^6.2.2",
     "dotenv": "^17.2.3",
+    "prettier": "3.8.1",
     "ts-json-schema-generator": "^2.4.0",
-    "typedoc": "^0.28.16",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3"
   }
 }