umami-api-js 0.2.0 → 0.2.1

package/README.md

@@ -1,5 +1,26 @@
-A package to interact with [the API of self-hosted instances of Umami](https://umami.is/docs/api). It is a 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).
+# umami-api-js
 
-If you are reading this from the [package's documentation](https://umami-api-js.taevas.xyz/), please be aware that the documentation is for **umami-api-js@0.2.0**, so make sure your package is up to date! Report any bug on [Codeberg](https://codeberg.org/Taevas/umami-api-js/issues).
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/V7V4J78L0)
 
-Please note that this package is expected to work with self-hosted instances of **Umami v3.0.3**, and is *not* expected to work with [Umami Cloud](https://umami.is/docs/cloud), the instance of Umami hosted by its creators.
+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)!
+
+## How to install and get started
+
+Before installing, if using Node.js, check if you're running version 20 or above:
+
+```bash
+node -v # displays your version of node.js
+```
+
+Then to install the package, use a command from your package manager:
+
+```bash
+npm i umami-api-js # if using npm
+yarn add umami-api-js # if using yarn
+pnpm add umami-api-js # if using pnpm
+bun a umami-api-js # if using bun
+```

package/dist/index.d.ts

@@ -82,7 +82,10 @@ export declare class APIError extends Error {
     method: Parameters<API["request"]>[0];
     endpoint: Parameters<API["request"]>[1];
     parameters: Parameters<API["request"]>[2];
-    status_code?: number | undefined;
+    response?: {
+        status_code: number;
+        json: unknown;
+    } | undefined;
     original_error?: Error | undefined;
     /**
      * @param message The reason why things didn't go as expected
@@ -93,14 +96,26 @@ export declare class APIError extends Error {
      * @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);
+    constructor(message: string, server: API["server"], method: Parameters<API["request"]>[0], endpoint: Parameters<API["request"]>[1], parameters: Parameters<API["request"]>[2], response?: {
+        status_code: number;
+        json: unknown;
+    } | 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>);
+    constructor(server: API["server"], username: API["username"], password: API["password"], settings?: Partial<API>);
+    /** You might want to use this constructor if you'd like the freedom to set whatever you like, for example a {@link API.token} without setting account credentials */
+    constructor(settings: Partial<API>);
+    /**
+     * The alternative way of creating an API instance, awaiting this method waits for the server's authorization
+     * and allows you to catch errors if the authorization fails
+     * @param server The base URL where requests should land, **should include the `/api` portion if applicable** (e.g. `https://my-instance.com/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 */
     get token(): string;
@@ -113,6 +128,10 @@ export declare class API {
     /** The expiration date of your token */
     get expires(): Date;
     set expires(date: Date);
+    private _server;
+    /** The base URL where requests should land, **should include the `/api` portion if applicable** */
+    get server(): string;
+    set server(server: string);
     private _username;
     /** The username of the account */
     get username(): string;
@@ -121,10 +140,6 @@ export declare class API {
     /** 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
@@ -151,6 +166,10 @@ export declare class API {
      * @returns Whether or not the token has changed (**should be true** as otherwise the server would complain and an {@link APIError} would be thrown to give you some details)
      */
     setNewToken(): Promise<boolean>;
+    private _set_token_on_creation;
+    /** 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(): 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**) */
     get set_token_on_401(): boolean;

package/dist/index.js

@@ -19,7 +19,7 @@ export class APIError extends Error {
     method;
     endpoint;
     parameters;
-    status_code;
+    response;
     original_error;
     /**
      * @param message The reason why things didn't go as expected
@@ -30,14 +30,14 @@ export class APIError extends Error {
      * @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) {
+    constructor(message, server, method, endpoint, parameters, response, original_error) {
         super();
         this.message = message;
         this.server = server;
         this.method = method;
         this.endpoint = endpoint;
         this.parameters = parameters;
-        this.status_code = status_code;
+        this.response = response;
         this.original_error = original_error;
         if (this.parameters?.password) {
             this.parameters.password = "<REDACTED>";
@@ -46,8 +46,8 @@ export class APIError extends Error {
 }
 /** 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;
+    constructor(server_or_settings, username, password, settings) {
+        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) => {
@@ -55,13 +55,38 @@ export class API {
             });
             Object.assign(this, settings);
         }
+        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 (typeof username_or_token === "string" && typeof password_or_settings === "string") {
-            this.username = username_or_token;
-            this.password = password_or_settings;
+        if (this.set_token_on_creation && typeof server_or_settings === "string" && username && password) {
+            this.server = server_or_settings;
+            this.username = username;
+            this.password = password;
             this.setNewToken();
         }
     }
+    /**
+     * The alternative way of creating an API instance, awaiting this method waits for the server's authorization
+     * and allows you to catch errors if the authorization fails
+     * @param server The base URL where requests should land, **should include the `/api` portion if applicable** (e.g. `https://my-instance.com/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) {
+            settings.set_token_on_creation = false;
+        }
+        else {
+            settings = { set_token_on_creation: false };
+        }
+        const new_api = new API({ server, username, password, ...settings });
+        // We set the token ourselves, which also means we'll be the first to throw if it fails, so the APIError should be useful to users
+        await new_api.setNewToken();
+        return new_api;
+    }
     _token = "";
     /** The key that allows you to talk with the API */
     get token() { return this._token; }
@@ -78,6 +103,10 @@ export class API {
         this.updateTokenTimer();
     }
     // 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; }
     _username = "";
     /** The username of the account */
     get username() { return this._username; }
@@ -86,10 +115,6 @@ export class API {
     /** 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",
@@ -138,7 +163,7 @@ export class API {
                     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));
+                        reject(new APIError(error_message, this.server, "post", ["auth", "login"], body, { status_code: response.status, json }));
                     }
                     // Note: `json` currently only has `token` & `user`
                     this.token = json.token;
@@ -157,6 +182,10 @@ export class API {
             this.log(false, "A new token has been set!");
         return old_token !== this.token;
     }
+    _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; }
@@ -351,7 +380,11 @@ export class API {
             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);
+            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;
     }

package/dist/namespaces/Events.d.ts

@@ -23,7 +23,10 @@ export declare namespace Events {
         hasData?: boolean;
     }
     /** Gets website event details within a given time range: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevents */
-    function get_WEBSITEID_Events(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps & GenericRequestParameters): Promise<Event[]>;
+    function get_WEBSITEID_Events(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & GenericRequestParameters & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<Event[]>;
     interface Data {
         websiteId: Websites.Website["id"];
         sessionId?: Sessions.Session["id"];
@@ -46,9 +49,11 @@ export declare namespace Events {
         total: number;
     }
     /** Gets event data names, properties, and counts: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-dataevents (TODO Server returns a 500) */
-    function get_WEBSITEID_EventdataEvents(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps & {
+    function get_WEBSITEID_EventdataEvents(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
         /** Event name filter */
         event?: Event["eventName"];
+        /** Can accept filter parameters */
+        filters?: Filters;
     }): Promise<DataMultiple[]>;
     interface DataFields {
         propertyName: string;
@@ -57,24 +62,32 @@ export declare namespace Events {
         total: number;
     }
     /** Gets event data property and value counts within a given time range: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-datafields */
-    function get_WEBSITEID_EventdataFields(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps): Promise<DataFields[]>;
+    function get_WEBSITEID_EventdataFields(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<DataFields[]>;
     interface DataProperties {
         eventName: Event["eventName"] | null;
         propertyName: string;
         total: number;
     }
     /** Gets event name and property counts for a website: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-dataproperties */
-    function get_WEBSITEID_EventdataProperties(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps): Promise<DataProperties[]>;
+    function get_WEBSITEID_EventdataProperties(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<DataProperties[]>;
     interface DataValues {
         value: string;
         total: number;
     }
     /** Gets event data counts for a given event and property: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-datavalues */
-    function get_WEBSITEID_EventdataValues(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps & {
+    function get_WEBSITEID_EventdataValues(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
         /** Event name filter */
         event: Event["eventName"];
         /** Property name */
         propertyName: string;
+        /** Can accept filter parameters */
+        filters?: Filters;
     }): Promise<DataValues[]>;
     interface DataStats {
         events: number;
@@ -82,5 +95,8 @@ export declare namespace Events {
         records: number;
     }
     /** Gets aggregated website events, properties, and records within a given time range: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-datastats */
-    function get_WEBSITEID_EventdataStats(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps): Promise<DataStats>;
+    function get_WEBSITEID_EventdataStats(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<DataStats>;
 }

package/dist/namespaces/Reports.d.ts

@@ -1,5 +1,5 @@
-import { API, DeletionResult, Filters, GenericRequestParameters, NameValue, Timestamps, Users, Websites, XTY } from "../index.js";
-/** Using reports throught the api: https://umami.is/docs/api/reports */
+import { API, DeletionResult, Filters, GenericRequestParameters, NameValue, Users, Websites, XTY } from "../index.js";
+/** Using reports throught [sic] the api: https://umami.is/docs/api/reports */
 export declare namespace Reports {
     interface Report {
         id: string;
@@ -15,46 +15,47 @@ export declare namespace Reports {
         createdAt: Date;
         updatedAt: Date;
     }
-    type ReportType = {
-        type: "attribution" | "breakdown" | "funnel" | "goal" | "journey" | "retention" | "revenue" | "utm";
-    };
-    interface UTM {
-        utm: string;
-        views: number;
+    /** The Reports endpoints use `startDate` instead of `startAt`, and `endDate` instead of `endAt` */
+    interface Timestamps {
+        /** Timestamp of starting date */
+        startDate: Date | number;
+        /** Timestamp of end date */
+        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) */
-    function get(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Omit<GenericRequestParameters, "search">): Promise<Report[]>;
-    /** Creates a report: https://umami.is/docs/api/reports#post-apireports (TODO UNTESTED) */
-    function post(this: API, websiteId: Websites.Website["id"], parameters: ReportType & {
+    function get(this: API, websiteId: Websites.Website["id"], parameters: {
+        type: ReportType;
+    } & Omit<GenericRequestParameters, "search">): Promise<Report[]>;
+    /** Creates a report: https://umami.is/docs/api/reports#post-apireports */
+    function post(this: API, websiteId: Websites.Website["id"], parameters: {
+        /** Report type */
+        type: ReportType;
         /** Name of report */
         name: Report["name"];
         /** Description of report */
         description?: Report["description"];
         /** Parameters for report */
-        parameters?: any;
+        parameters: Report["parameters"];
     }): Promise<Report>;
-    /** Gets a report by ID: https://umami.is/docs/api/reports#get-apireportsreportid (TODO UNTESTED) */
+    /** Gets a report by ID: https://umami.is/docs/api/reports#get-apireportsreportid */
     function get_REPORTID(this: API, reportId: Report["id"]): Promise<Report>;
-    /** Updates a report: https://umami.is/docs/api/reports#post-apireportsreportid (TODO UNTESTED) */
-    function post_REPORTID(this: API, reportId: Report["id"], websiteId: Websites.Website["id"], parameters: ReportType & {
+    /** 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"];
+        /** Report type */
+        type?: ReportType;
         /** Name of report */
-        name: Report["name"];
+        name?: Report["name"];
         /** Description of report */
         description?: Report["description"];
         /** Parameters for report */
-        parameters?: any;
+        parameters?: Report["parameters"];
     }): Promise<Report>;
-    /** Deletes a report: https://umami.is/docs/api/reports#delete-apireportsreportid (TODO UNTESTED) */
+    /** Deletes a report: https://umami.is/docs/api/reports#delete-apireportsreportid */
     function delete_REPORTID(this: API, reportId: Report["id"]): Promise<DeletionResult>;
-    /** See how users engage with your marketing and what drives conversions: https://umami.is/docs/api/reports#post-apireportsattribution (TODO UNTESTED) */
-    function postAttribution(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Filters & Timestamps & {
-        /** Attribution model */
-        model: "firstClick" | "lastClick";
-        /** Conversion type */
-        type: ("path" | "event")[];
-        /** Conversion step */
-        step: string;
-    }): Promise<{
+    interface Attribution {
         referrer: NameValue[];
         paidAds: NameValue[];
         utm_source: NameValue[];
@@ -67,11 +68,19 @@ export declare namespace Reports {
             visitors: number;
             visits: number;
         };
-    }>;
-    /** Dive deeper into your data by using segments and filters: https://umami.is/docs/api/reports#post-apireportsbreakdown (TODO UNTESTED) */
-    function postBreakdown(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Filters & Timestamps & {
-        fields: ("path" | "title" | "query" | "referrer" | "browser" | "os" | "device" | "country" | "region" | "city" | "hostname" | "tag" | "event")[];
-    }): Promise<{
+    }
+    /** See how users engage with your marketing and what drives conversions: https://umami.is/docs/api/reports#post-apireportsattribution */
+    function postAttribution(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+        /** Attribution model */
+        model: "first-click" | "last-click";
+        /** Conversion type */
+        type: "path" | "event";
+        /** Conversion step */
+        step: string;
+    }): Promise<Attribution>;
+    interface Breakdown {
         views: number;
         visitors: number;
         visits: number;
@@ -79,9 +88,27 @@ export declare namespace Reports {
         totaltime: number;
         os: string;
         country: string;
-    }[]>;
-    /** Understand the conversion and drop-off rate of users: https://umami.is/docs/api/reports#post-apireportsfunnel (TODO UNTESTED) */
-    function postFunnel(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Filters & Timestamps & {
+    }
+    /** Dive deeper into your data by using segments and filters: https://umami.is/docs/api/reports#post-apireportsbreakdown */
+    function postBreakdown(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+        /** List of column fields */
+        fields: ("path" | "title" | "query" | "referrer" | "browser" | "os" | "device" | "country" | "region" | "city" | "hostname" | "tag" | "event")[];
+    }): Promise<Breakdown[]>;
+    interface Funnel {
+        type: string;
+        value: string;
+        visitors: number;
+        previous: number;
+        dropped: number;
+        dropoff: number | null;
+        remaining: number | null;
+    }
+    /** Understand the conversion and drop-off rate of users: https://umami.is/docs/api/reports#post-apireportsfunnel */
+    function postFunnel(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
         /** Type of event and conversion step */
         steps: {
             type: "path" | "event";
@@ -89,70 +116,82 @@ export declare namespace Reports {
         }[];
         /** Window of days between funnel steps to be considered a conversion */
         window: number;
-    }): Promise<{
-        type: string;
-        value: string;
-        visitors: number;
-        previous: number;
-        dropped: number;
-        dropoff: number | null;
-        remaining: number;
-    }[]>;
+    }): Promise<Funnel[]>;
+    interface Goals {
+        num: number;
+        total: number;
+    }
     /** Track your goals for pageviews and events: https://umami.is/docs/api/reports#post-apireportsgoals (TODO UNTESTED) */
-    function postGoals(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Filters & Timestamps & {
+    function postGoals(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
         /** Conversion type */
-        type: ("path" | "event")[];
+        type: "path" | "event";
         /** Conversion step value */
         value: string;
-    }): Promise<{
-        num: number;
-        total: number;
-    }>;
-    /** Understand how users nagivate through your website: https://umami.is/docs/api/reports#post-apireportsjourney (TODO UNTESTED) */
-    function postJourney(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Filters & Timestamps & {
+    }): Promise<Goals>;
+    interface Journey {
+        items: (string | null)[];
+        count: number;
+    }
+    /** Understand how users nagivate [sic] through your website: https://umami.is/docs/api/reports#post-apireportsjourney */
+    function postJourney(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
         /** Number of steps from 3 to 7 */
         steps: number;
         /** Starting step URL or event name */
         startStep: string;
         /** Ending step URL or event name */
         endStep?: string;
-    }): Promise<{
-        items: (string | null)[];
-        count: number;
-    }[]>;
-    /** Measure your website stickiness by tracking how often users return: https://umami.is/docs/api/reports#post-apireportsretention (TODO UNTESTED) */
-    function postRetention(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Filters & Timestamps & {
-        /** Timezone (ex. America/Los_Angeles) */
-        timezone: string;
-    }): Promise<{
+    }): Promise<Journey[]>;
+    interface Retention {
         date: Date;
         day: number;
         visitors: number;
         returnVisitors: number;
         percentage: number;
-    }[]>;
-    /** Get currency for given range. Needed for Revenue and optional in Attribution reports: https://umami.is/docs/api/reports#post-apireportsrevenue (TODO UNTESTED) */
-    function postRevenue(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Filters & Timestamps & {
+    }
+    /** Measure your website stickiness by tracking how often users return: https://umami.is/docs/api/reports#post-apireportsretention */
+    function postRetention(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
         /** Timezone (ex. America/Los_Angeles) */
         timezone: string;
-        /** Currency code (ISO 4217) */
-        currency: string;
-    }): Promise<{
+    }): Promise<Retention[]>;
+    interface Revenue {
         chart: XTY[];
         country: NameValue[];
         total: {
-            sum: number;
+            sum: number | null;
             count: number;
             unique_count: number;
             average: number;
         };
-    }>;
-    /** Track your campaigns through UTM parameters: https://umami.is/docs/api/reports#post-apireportsutm (TODO UNTESTED) */
-    function postUTM(this: API, websiteId: Websites.Website["id"], parameters: ReportType & Filters & Timestamps): Promise<{
-        utm_source: UTM[];
-        utm_medium: UTM[];
-        utm_campaign: UTM[];
-        utm_term: UTM[];
-        utm_content: UTM[];
-    }>;
+    }
+    /** Get currency for given range. Needed for Revenue and optional in Attribution reports: https://umami.is/docs/api/reports#post-apireportsrevenue */
+    function postRevenue(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+        /** Timezone (ex. America/Los_Angeles) */
+        timezone: string;
+        /** Currency code (ISO 4217) */
+        currency: string;
+    }): Promise<Revenue>;
+    interface UTMProperty {
+        utm: string;
+        views: number;
+    }
+    interface UTM {
+        utm_source: UTMProperty[];
+        utm_medium: UTMProperty[];
+        utm_campaign: UTMProperty[];
+        utm_term: UTMProperty[];
+        utm_content: UTMProperty[];
+    }
+    /** Track your campaigns through UTM parameters: https://umami.is/docs/api/reports#post-apireportsutm */
+    function postUTM(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<UTM>;
 }

package/dist/namespaces/Reports.js

@@ -1,4 +1,4 @@
-/** Using reports throught the api: https://umami.is/docs/api/reports */
+/** 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) */
@@ -7,64 +7,107 @@ export var Reports;
         return response.data;
     }
     Reports.get = get;
-    /** Creates a report: https://umami.is/docs/api/reports#post-apireports (TODO UNTESTED) */
+    /** Creates a report: https://umami.is/docs/api/reports#post-apireports */
     async function post(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 (TODO UNTESTED) */
+    /** Gets a report by ID: https://umami.is/docs/api/reports#get-apireportsreportid */
     async function get_REPORTID(reportId) {
         return await this.request("get", ["reports", reportId]);
     }
     Reports.get_REPORTID = get_REPORTID;
-    /** Updates a report: https://umami.is/docs/api/reports#post-apireportsreportid (TODO UNTESTED) */
-    async function post_REPORTID(reportId, websiteId, parameters) {
-        return await this.request("get", ["reports", reportId], { websiteId, ...parameters });
+    /** 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);
     }
     Reports.post_REPORTID = post_REPORTID;
-    /** Deletes a report: https://umami.is/docs/api/reports#delete-apireportsreportid (TODO UNTESTED) */
+    /** Deletes a report: https://umami.is/docs/api/reports#delete-apireportsreportid */
     async function delete_REPORTID(reportId) {
         return await this.request("delete", ["reports", reportId]);
     }
     Reports.delete_REPORTID = delete_REPORTID;
-    /** See how users engage with your marketing and what drives conversions: https://umami.is/docs/api/reports#post-apireportsattribution (TODO UNTESTED) */
+    /** Private function to deal more easily with the post functions that don't involve actual reports */
+    async function postNonReports(api, type, websiteId, filters, parameters) {
+        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 });
+    }
+    /** See how users engage with your marketing and what drives conversions: https://umami.is/docs/api/reports#post-apireportsattribution */
     async function postAttribution(websiteId, parameters) {
-        return await this.request("post", ["reports", "attribution"], { websiteId, ...parameters });
+        return await postNonReports(this, "attribution", websiteId, parameters.filters, {
+            startDate: parameters.startDate,
+            endDate: parameters.endDate,
+            model: parameters.model,
+            type: parameters.type,
+            step: parameters.step,
+        });
     }
     Reports.postAttribution = postAttribution;
-    /** Dive deeper into your data by using segments and filters: https://umami.is/docs/api/reports#post-apireportsbreakdown (TODO UNTESTED) */
+    /** Dive deeper into your data by using segments and filters: https://umami.is/docs/api/reports#post-apireportsbreakdown */
     async function postBreakdown(websiteId, parameters) {
-        return await this.request("post", ["reports", "breakdown"], { websiteId, ...parameters });
+        return await postNonReports(this, "breakdown", websiteId, parameters.filters, {
+            startDate: parameters.startDate,
+            endDate: parameters.endDate,
+            fields: parameters.fields,
+        });
     }
     Reports.postBreakdown = postBreakdown;
-    /** Understand the conversion and drop-off rate of users: https://umami.is/docs/api/reports#post-apireportsfunnel (TODO UNTESTED) */
+    /** Understand the conversion and drop-off rate of users: https://umami.is/docs/api/reports#post-apireportsfunnel */
     async function postFunnel(websiteId, parameters) {
-        return await this.request("post", ["reports", "funnel"], { websiteId, ...parameters });
+        return await postNonReports(this, "funnel", websiteId, parameters.filters, {
+            startDate: parameters.startDate,
+            endDate: parameters.endDate,
+            steps: parameters.steps,
+            window: parameters.window,
+        });
     }
     Reports.postFunnel = postFunnel;
     /** Track your goals for pageviews and events: https://umami.is/docs/api/reports#post-apireportsgoals (TODO UNTESTED) */
     async function postGoals(websiteId, parameters) {
-        return await this.request("post", ["reports", "goals"], { websiteId, ...parameters });
+        return await postNonReports(this, "goal", websiteId, parameters.filters, {
+            startDate: parameters.startDate,
+            endDate: parameters.endDate,
+            type: parameters.type,
+            value: parameters.value,
+        });
     }
     Reports.postGoals = postGoals;
-    /** Understand how users nagivate through your website: https://umami.is/docs/api/reports#post-apireportsjourney (TODO UNTESTED) */
+    /** Understand how users nagivate [sic] through your website: https://umami.is/docs/api/reports#post-apireportsjourney */
     async function postJourney(websiteId, parameters) {
-        return await this.request("post", ["reports", "journey"], { websiteId, ...parameters });
+        return await postNonReports(this, "journey", websiteId, parameters.filters, {
+            startDate: parameters.startDate,
+            endDate: parameters.endDate,
+            steps: parameters.steps,
+            startStep: parameters.startStep,
+            endStep: parameters.endStep,
+        });
     }
     Reports.postJourney = postJourney;
-    /** Measure your website stickiness by tracking how often users return: https://umami.is/docs/api/reports#post-apireportsretention (TODO UNTESTED) */
+    /** Measure your website stickiness by tracking how often users return: https://umami.is/docs/api/reports#post-apireportsretention */
     async function postRetention(websiteId, parameters) {
-        return await this.request("post", ["reports", "retention"], { websiteId, ...parameters });
+        return await postNonReports(this, "retention", websiteId, parameters.filters, {
+            startDate: parameters.startDate,
+            endDate: parameters.endDate,
+            timezone: parameters.timezone,
+        });
     }
     Reports.postRetention = postRetention;
-    /** Get currency for given range. Needed for Revenue and optional in Attribution reports: https://umami.is/docs/api/reports#post-apireportsrevenue (TODO UNTESTED) */
+    /** Get currency for given range. Needed for Revenue and optional in Attribution reports: https://umami.is/docs/api/reports#post-apireportsrevenue */
     async function postRevenue(websiteId, parameters) {
-        return await this.request("post", ["reports", "revenue"], { websiteId, ...parameters });
+        return await postNonReports(this, "revenue", websiteId, parameters.filters, {
+            startDate: parameters.startDate,
+            endDate: parameters.endDate,
+            timezone: parameters.timezone,
+            currency: parameters.currency,
+        });
     }
     Reports.postRevenue = postRevenue;
-    /** Track your campaigns through UTM parameters: https://umami.is/docs/api/reports#post-apireportsutm (TODO UNTESTED) */
+    /** Track your campaigns through UTM parameters: https://umami.is/docs/api/reports#post-apireportsutm */
     async function postUTM(websiteId, parameters) {
-        return await this.request("post", ["reports", "utm"], { websiteId, ...parameters });
+        return await postNonReports(this, "utm", websiteId, parameters.filters, {
+            startDate: parameters.startDate,
+            endDate: parameters.endDate,
+        });
     }
     Reports.postUTM = postUTM;
 })(Reports || (Reports = {}));

package/dist/namespaces/Sessions.d.ts

@@ -22,7 +22,10 @@ export declare namespace Sessions {
         createdAt: Date;
     }
     /** Gets website session details within a given time range: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessions */
-    function get_WEBSITEID_Sessions(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps & GenericRequestParameters): Promise<SessionWithHostnameCreatedate[]>;
+    function get_WEBSITEID_Sessions(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & GenericRequestParameters & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<SessionWithHostnameCreatedate[]>;
     interface Stats {
         /** Pages hits */
         pageviews: {
@@ -54,10 +57,16 @@ export declare namespace Sessions {
         };
     }
     /** Gets summarized website session statistics: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessionsstats */
-    function get_WEBSITEID_SessionsStats(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps): Promise<Stats>;
+    function get_WEBSITEID_SessionsStats(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<Stats>;
     /** Get collected count of sessions by hour of weekday: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessionsweekly */
-    function get_WEBSITEID_SessionsWeekly(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps & {
+    function get_WEBSITEID_SessionsWeekly(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Timezone (ex. America/Los_Angeles) */
         timezone: string;
+        /** Can accept filter parameters */
+        filters?: Filters;
     }): Promise<number[][]>;
     interface SessionWithDistinctidEventsTotaltime extends Session {
         distinctId: string | null;
@@ -96,13 +105,19 @@ export declare namespace Sessions {
         total: number;
     }
     /** Gets session data counts by property name: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-dataproperties (TODO Server returns empty array) */
-    function get_WEBSITEID_SessiondataProperties(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps): Promise<DataProperties[]>;
+    function get_WEBSITEID_SessiondataProperties(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<DataProperties[]>;
     interface DataValues {
         value: string;
         total: number;
     }
     /** Gets session data counts for a given property: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-datavalues (TODO Server returns empty array) */
-    function get_WEBSITEID_SessiondataValues(this: API, websiteId: Websites.Website["id"], parameters: Filters & Timestamps & {
+    function get_WEBSITEID_SessiondataValues(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Property name */
         propertyName: string;
+        /** Can accept filter parameters */
+        filters?: Filters;
     }): Promise<DataValues[]>;
 }

package/dist/namespaces/WebsiteStats.d.ts

@@ -35,16 +35,20 @@ export declare namespace WebsiteStats {
         visitors: number;
     }>;
     /** Gets events within a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteideventsseries */
-    function get_WEBSITEID_EventsSeries(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & Units & Filters & {
+    function get_WEBSITEID_EventsSeries(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & Units & {
+        /** Can accept filter parameters */
+        filters?: Filters;
         /** Timezone (ex. America/Los_Angeles) */
         timezone: string;
     }): Promise<XTY[]>;
     /** Gets metrics for a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidmetrics (TODO UNTESTED) */
-    function get_WEBSITEID_Metrics(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & Units & Filters & {
+    function get_WEBSITEID_Metrics(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & Units & {
         /** Timezone (ex. America/Los_Angeles) */
         timezone: string;
         /** Metrics type */
         type: MetricsTypes;
+        /** Can accept filter parameters */
+        filters?: Filters;
         /** (optional, default 500) Number of rows returned */
         limit?: number;
         /** (optional, default 0) Number of ows to skip */
@@ -61,11 +65,13 @@ export declare namespace WebsiteStats {
         name: string;
     })[]>;
     /** Gets pageviews within a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidpageviews (TODO UNTESTED) */
-    function get_WEBSITEID_Pageviews(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & Units & Filters & {
+    function get_WEBSITEID_Pageviews(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & Units & {
         /** Timezone (ex. America/Los_Angeles) */
         timezone: string;
         /** Comparison value `prev` | `yoy` */
         compare?: string;
+        /** Can accept filter parameters */
+        filters?: Filters;
     }): Promise<{
         pageviews: {
             /** Timestamp */
@@ -81,9 +87,9 @@ export declare namespace WebsiteStats {
         }[];
     }>;
     /** Gets summarized website statistics: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidstats (TODO UNTESTED) */
-    function get_WEBSITEID_Stats(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & Filters & Units & {
-        /** Timezone (ex. America/Los_Angeles) */
-        timezone: string;
+    function get_WEBSITEID_Stats(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
     }): Promise<Stats & {
         comparison: Stats;
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umami-api-js",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Package to easily access the Umami api!",
   "type": "module",
   "main": "dist/index.js",