umami-api-js 1.0.0 → 1.0.1

package/README.md

@@ -82,13 +82,14 @@ const api = new umami.API("<api_endpoint>", "<username>", "<password>", {
 
 ### Tokens
 
-An [`access_token`](https://umami-api-js.taevas.xyz/classes/API.html#access_token) is required to access the API, and should be valid for 24 hours. 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! But how about after those 24 hours?
+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!
 
-Once an `access_token` has become invalid, the server will no longer respond correctly to requests made with it, instead responding with [401](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/401). Thankfully, there are solutions to get and set new `access_token`s in a convenient way, so there is no need to create a new `api` object every day!
+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!
 
-- If you'd like to manually get a new `access_token`, calling [`setNewToken()`](https://umami-api-js.taevas.xyz/classes/API.html#setnewtoken) will replace your previous token with a new one
-- 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 it 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 true, which (as its name indicates) will do that upon encountering a 401
+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.

package/dist/index.d.ts

@@ -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

@@ -62,14 +62,17 @@ export class API {
             // 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();
         }
     }
@@ -110,8 +113,12 @@ export class API {
     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 */
+    _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;
     }
@@ -179,7 +186,9 @@ export class API {
     /** 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
@@ -204,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();
                 });
             })
@@ -226,8 +236,8 @@ export class API {
     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**) */
+    _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;
     }
@@ -386,7 +396,9 @@ export class API {
         let error_object;
         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)) {
             // Convert Dates to ms
             if (typeof v === "object" && !Array.isArray(v) && v !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umami-api-js",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Package to easily access the Umami api!",
   "type": "module",
   "main": "dist/index.js",
@@ -32,12 +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"
   }
 }