umami-api-js 0.2.1 → 0.2.2

package/README.md

@@ -24,3 +24,24 @@ yarn add umami-api-js # if using yarn
 pnpm add umami-api-js # if using pnpm
 bun a umami-api-js # if using bun
 ```
+
+Finally, you will want to create an API object, which you will use for essentially all of your requests. You can do something like that:
+
+```typescript
+// TypeScript
+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
+
+// 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"});
+
+  console.log(`This website recently had ${stats.visits} visits from ${stats.visitors} visitors!`);
+}
+
+displayStats("f196d626-e609-4841-9a80-0dc60f523ed5");
+```

package/dist/index.d.ts

@@ -93,7 +93,7 @@ export declare class APIError extends Error {
      * @param method The method used for this request (like "get", "post", etc...)
      * @param endpoint The type of resource that was requested from the server
      * @param parameters The filters that were used to specify what resource was wanted
-     * @param status_code The status code that was returned by the server, if there is one
+     * @param response The status code and the original body 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], response?: {
@@ -277,7 +277,7 @@ export declare class API {
         data?: {
             [k: string]: any;
         };
-    }): Promise<{
+    }, type?: "event" | "identify"): Promise<{
         cache: string;
         sessionId: Events.Event["sessionId"];
         visitId: string;

package/dist/index.js

@@ -27,7 +27,7 @@ export class APIError extends Error {
      * @param method The method used for this request (like "get", "post", etc...)
      * @param endpoint The type of resource that was requested from the server
      * @param parameters The filters that were used to specify what resource was wanted
-     * @param status_code The status code that was returned by the server, if there is one
+     * @param response The status code and the original body 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, response, original_error) {
@@ -423,8 +423,8 @@ export class API {
      * To register an event
      * @group Sending stats
      */
-    async sendStats(websiteId, payload) {
-        return await this.request("post", ["send"], { payload: { website: websiteId, ...payload }, type: "event" });
+    async sendStats(websiteId, payload, type = "event") {
+        return await this.request("post", ["send"], { payload: { website: websiteId, ...payload }, type });
     }
     // ADMIN
     /** @group Admin endpoints */

package/dist/namespaces/Events.d.ts

@@ -46,9 +46,14 @@ export declare namespace Events {
         eventName: Event["eventName"];
         propertyName: string;
         dataType: number;
+        propertyValue: string | number;
         total: number;
     }
-    /** Gets event data names, properties, and counts: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-dataevents (TODO Server returns a 500) */
+    /**
+     * Gets event data names, properties, and counts: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-dataevents
+     * @remarks At least on Umami v3.0.3 and likely prior versions, **this will not work if not using the optional event name filter**
+     * https://github.com/umami-software/umami/issues/3837
+     */
     function get_WEBSITEID_EventdataEvents(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
         /** Event name filter */
         event?: Event["eventName"];

package/dist/namespaces/Events.js

@@ -12,7 +12,11 @@ export var Events;
         return await this.request("get", ["websites", websiteId, "event-data", eventId]);
     }
     Events.get_WEBSITEID_Eventdata_EVENTID = get_WEBSITEID_Eventdata_EVENTID;
-    /** Gets event data names, properties, and counts: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-dataevents (TODO Server returns a 500) */
+    /**
+     * Gets event data names, properties, and counts: https://umami.is/docs/api/events#get-apiwebsiteswebsiteidevent-dataevents
+     * @remarks At least on Umami v3.0.3 and likely prior versions, **this will not work if not using the optional event name filter**
+     * https://github.com/umami-software/umami/issues/3837
+     */
     async function get_WEBSITEID_EventdataEvents(websiteId, parameters) {
         return await this.request("get", ["websites", websiteId, "event-data", "events"], parameters);
     }

package/dist/namespaces/Sessions.d.ts

@@ -7,7 +7,7 @@ export declare namespace Sessions {
         browser: string | null;
         os: string | null;
         device: string;
-        screen: string;
+        screen: string | null;
         language: string | null;
         country: string;
         region: string;
@@ -98,13 +98,13 @@ export declare namespace Sessions {
         dateValue: Date | null;
         createdAt: Date;
     }
-    /** Gets session properties for a individual session: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessionssessionidproperties (TODO Server returns empty array) */
+    /** Gets session properties for a individual session: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsessionssessionidproperties */
     function get_WEBSITEID_Sessions_SESSIONID_Properties(this: API, websiteId: Websites.Website["id"], sessionId: Session["id"]): Promise<Properties[]>;
     interface DataProperties {
         propertyName: string;
         total: number;
     }
-    /** Gets session data counts by property name: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-dataproperties (TODO Server returns empty array) */
+    /** Gets session data counts by property name: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-dataproperties */
     function get_WEBSITEID_SessiondataProperties(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
         /** Can accept filter parameters */
         filters?: Filters;
@@ -113,7 +113,7 @@ export declare namespace Sessions {
         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) */
+    /** Gets session data counts for a given property: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-datavalues */
     function get_WEBSITEID_SessiondataValues(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
         /** Property name */
         propertyName: string;

package/dist/namespaces/Sessions.js

@@ -29,17 +29,17 @@ export var Sessions;
         return await this.request("get", ["websites", websiteId, "sessions", sessionId, "activity"], parameters);
     }
     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 (TODO Server returns empty array) */
+    /** 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"]);
     }
     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 (TODO Server returns empty array) */
+    /** Gets session data counts by property name: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-dataproperties */
     async function get_WEBSITEID_SessiondataProperties(websiteId, parameters) {
         return await this.request("get", ["websites", websiteId, "session-data", "properties"], parameters);
     }
     Sessions.get_WEBSITEID_SessiondataProperties = get_WEBSITEID_SessiondataProperties;
-    /** Gets session data counts for a given property: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-datavalues (TODO Server returns empty array) */
+    /** Gets session data counts for a given property: https://umami.is/docs/api/sessions#get-apiwebsiteswebsiteidsession-datavalues */
     async function get_WEBSITEID_SessiondataValues(websiteId, parameters) {
         return await this.request("get", ["websites", websiteId, "session-data", "values"], parameters);
     }

package/dist/namespaces/WebsiteStats.d.ts

@@ -30,10 +30,12 @@ export declare namespace WebsiteStats {
         totaltime: number;
     }
     type MetricsTypes = "path" | "entry" | "exit" | "title" | "query" | "referrer" | "channel" | "domain" | "country" | "region" | "city" | "browser" | "os" | "device" | "language" | "screen" | "event" | "hostname" | "tag";
-    /** Gets the number of active users on a website: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidactive */
-    function get_WEBSITEID_Active(this: API, websiteId: Websites.Website["id"]): Promise<{
+    interface Active {
+        /** Number of unique visitors within the last 5 minutes */
         visitors: number;
-    }>;
+    }
+    /** Gets the number of active users on a website: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidactive */
+    function get_WEBSITEID_Active(this: API, websiteId: Websites.Website["id"]): Promise<Active>;
     /** 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 & {
         /** Can accept filter parameters */
@@ -41,7 +43,13 @@ export declare namespace WebsiteStats {
         /** 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) */
+    interface Metrics {
+        /** Unique value, depending on metric type */
+        x: string;
+        /** Number of visitors */
+        y: number;
+    }
+    /** Gets metrics for a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidmetrics */
     function get_WEBSITEID_Metrics(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & Units & {
         /** Timezone (ex. America/Los_Angeles) */
         timezone: string;
@@ -53,26 +61,14 @@ export declare namespace WebsiteStats {
         limit?: number;
         /** (optional, default 0) Number of ows to skip */
         offset?: number;
-    }): Promise<{
-        /** Unique value, depending on metric type */
-        x: string;
-        /** Number of visitors */
-        y: number;
-    }[]>;
-    /** Gets expanded metrics for a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidmetricsexpanded (TODO UNTESTED) */
-    function get_WEBSITEID_MetricsExpanded(this: API, ...args: Parameters<typeof get_WEBSITEID_Metrics>): Promise<(Stats & {
+    }): Promise<Metrics[]>;
+    interface ExpandedMetrics extends Stats {
         /** Unique value, depending on metric type */
         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 & {
-        /** Timezone (ex. America/Los_Angeles) */
-        timezone: string;
-        /** Comparison value `prev` | `yoy` */
-        compare?: string;
-        /** Can accept filter parameters */
-        filters?: Filters;
-    }): Promise<{
+    }
+    /** Gets expanded metrics for a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidmetricsexpanded */
+    function get_WEBSITEID_MetricsExpanded(this: API, ...args: Parameters<typeof get_WEBSITEID_Metrics>): Promise<ExpandedMetrics[]>;
+    interface Pageviews {
         pageviews: {
             /** Timestamp */
             x: Date;
@@ -85,12 +81,22 @@ export declare namespace WebsiteStats {
             /** Number of pageviews or visitors */
             y: number;
         }[];
-    }>;
-    /** 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 & {
+    }
+    /** Gets pageviews within a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidpageviews */
+    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<Stats & {
+    }): Promise<Pageviews>;
+    interface StatsWithComparison extends Stats {
         comparison: Stats;
-    }>;
+    }
+    /** Gets summarized website statistics: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidstats */
+    function get_WEBSITEID_Stats(this: API, websiteId: Websites.Website["id"], parameters: Timestamps & {
+        /** Can accept filter parameters */
+        filters?: Filters;
+    }): Promise<StatsWithComparison>;
 }

package/dist/namespaces/WebsiteStats.js

@@ -11,22 +11,22 @@ export var WebsiteStats;
         return await this.request("get", ["websites", websiteId, "events", "series"], parameters);
     }
     WebsiteStats.get_WEBSITEID_EventsSeries = get_WEBSITEID_EventsSeries;
-    /** Gets metrics for a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidmetrics (TODO UNTESTED) */
+    /** Gets metrics for a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidmetrics */
     async function get_WEBSITEID_Metrics(websiteId, parameters) {
         return await this.request("get", ["websites", websiteId, "metrics"], parameters);
     }
     WebsiteStats.get_WEBSITEID_Metrics = get_WEBSITEID_Metrics;
-    /** Gets expanded metrics for a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidmetricsexpanded (TODO UNTESTED) */
+    /** Gets expanded metrics for a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidmetricsexpanded */
     async function get_WEBSITEID_MetricsExpanded(...args) {
         return await this.request("get", ["websites", args[0], "metrics", "expanded"], args[1]);
     }
     WebsiteStats.get_WEBSITEID_MetricsExpanded = get_WEBSITEID_MetricsExpanded;
-    /** Gets pageviews within a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidpageviews (TODO UNTESTED) */
+    /** Gets pageviews within a given time range: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidpageviews */
     async function get_WEBSITEID_Pageviews(websiteId, parameters) {
         return await this.request("get", ["websites", websiteId, "pageviews"], parameters);
     }
     WebsiteStats.get_WEBSITEID_Pageviews = get_WEBSITEID_Pageviews;
-    /** Gets summarized website statistics: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidstats (TODO UNTESTED) */
+    /** Gets summarized website statistics: https://umami.is/docs/api/website-stats#get-apiwebsiteswebsiteidstats */
     async function get_WEBSITEID_Stats(websiteId, parameters) {
         return await this.request("get", ["websites", websiteId, "stats"], parameters);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umami-api-js",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Package to easily access the Umami api!",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,7 @@
     "prepublish": "npm run build",
     "build": "tsc",
     "test": "npm run build && node ./dist/test.js",
-    "docs": "npx typedoc lib/index.ts"
+    "docs": "npx typedoc lib/index.ts --cname umami-api-js.taevas.xyz --plugin ./docs_plugins/visitors.ts"
   },
   "engines": {
     "node": ">=20.0.0"