@darseen/vaze 2.5.0 → 2.6.0

package/README.md

@@ -10,6 +10,8 @@
 
 **@darseen/vaze** The official JavaScript/TypeScript SDK for Vaze, a self-hosted, local-first file storage and hosting service. This SDK provides a simple and type-safe way to interact with your Vaze instance's API from your Node.js backend or frontend applications.
 
+**[Website](https://vaze.darseen.dev)**  |  **[SDK documentation](https://vaze.darseen.dev/docs/sdk)**
+
 ## </div>
 
 # Installation
@@ -301,7 +303,7 @@ if (data) {
 
 # Account and Stats
 
-`vaze.me()` returns the caller's account and the scopes it may use. `vaze.stats()` returns the dashboard's numbers, with each section `null` when the caller lacks its scope.
+`vaze.me()` returns the caller's account and the scopes it may use. `vaze.stats()` returns the dashboard's numbers: storage, files added per day, public hosting traffic, API key usage, accounts and alerts, with each section `null` when the caller lacks its scope. Fields added in later server versions, such as `hosting` and `alerts`, are absent on older servers.
 
 ```ts
 const { data } = await vaze.me();
@@ -312,4 +314,4 @@ Failed requests carry the HTTP status in `error.status`, such as `401` once a se
 
 # Types
 
-This SDK is built with TypeScript and exports all necessary types to ensure type safety in your applications. Types such as `File`, `Folder`, `ApiKey`, `Activity`, `User`, `Session`, `InstanceSettings`, `ApiResponse`, `ListOptions`, and `VazeOptions`.
+This SDK is built with TypeScript and exports all necessary types to ensure type safety in your applications. Types such as `File`, `Folder`, `ApiKey`, `Activity`, `User`, `Session`, `InstanceSettings`, `Stats`, `StatsAlert`, `TrafficDay`, `ApiKeyUsage`, `ApiResponse`, `ListOptions`, and `VazeOptions`.

package/dist/index.cjs

@@ -606,27 +606,37 @@ var Vaze = class extends Base {
   }
   /** Dashboard numbers, with each section limited to the caller's scopes. */
   async stats() {
-    const { data, error } = await this.request(
+    const response = await this.request(
       "GET",
       this.apiUrl("/api/stats")
     );
-    const files = _optionalChain([data, 'optionalAccess', _7 => _7.files]);
+    if (response.data === null) return response;
+    const { files, hosting } = response.data;
+    const vazeUrl = this.vazeUrl;
+    const withUrl = (file) => ({
+      ...file,
+      url: constructFileUrls({ vazeUrl, files: [file] })[0].url
+    });
     return {
-      error,
-      data: data ? {
-        ...data,
+      error: null,
+      data: {
+        ...response.data,
         files: files ? {
           ...files,
-          largest: constructFileUrls({
-            vazeUrl: this.vazeUrl,
-            files: files.largest
-          }),
-          recent: constructFileUrls({
-            vazeUrl: this.vazeUrl,
-            files: files.recent
-          })
-        } : null
-      } : null
+          largest: constructFileUrls({ vazeUrl, files: files.largest }),
+          recent: constructFileUrls({ vazeUrl, files: files.recent })
+        } : null,
+        // servers that predate traffic leave `hosting` out, so keep it out
+        ...hosting ? {
+          hosting: {
+            ...hosting,
+            top: hosting.top.map((entry) => ({
+              ...entry,
+              file: withUrl(entry.file)
+            }))
+          }
+        } : {}
+      }
     };
   }
 };

package/dist/index.d.cts

@@ -1144,14 +1144,76 @@ type InstanceSettings = {
     visibilityCounts: Record<Visibility, number>;
     limits: Limits;
 };
+/** One API key's share of the week's requests. */
+type ApiKeyUsage = {
+    id: string;
+    name: string;
+    /** Requests over the same seven UTC days as `Stats["apiKeys"]["requests"]`. */
+    requests: number;
+    lastUsed: string | null;
+    expiresAt: string | null;
+};
+/** Public hosting traffic for one UTC day. */
+type TrafficDay = {
+    date: string;
+    /** Responses that served a file: 200, 206 and 304. */
+    requests: number;
+    /** Body bytes streamed out. */
+    bytes: number;
+    /** Requests for keys that matched no file the caller could read. */
+    notFound: number;
+};
+/** Something on the instance worth acting on. */
+type StatsAlert = 
+/** The data volume has less than a tenth of its space left. */
+{
+    type: "storage-low";
+    available: number;
+    capacity: number;
+}
+/** The caller's own uploads that failed over the last seven days. */
+ | {
+    type: "uploads-failed";
+    count: number;
+    latest: string;
+}
+/** The caller's own file and folder deletes that failed over the last seven days. */
+ | {
+    type: "deletes-failed";
+    count: number;
+    latest: string;
+}
+/** The caller's keys past their expiry date, which no longer work. */
+ | {
+    type: "keys-expired";
+    count: number;
+}
+/** The caller's keys that expire within seven days. */
+ | {
+    type: "keys-expiring";
+    count: number;
+}
+/** The caller's keys not used for 30 days. */
+ | {
+    type: "keys-unused";
+    count: number;
+};
+/**
+ * Fields marked optional were added after the first release of this endpoint.
+ * Servers that predate them leave them out, so check before reading.
+ */
 type Stats = {
     /** Present when the caller holds `files:read`. */
     files: {
         total: number;
         folders: number;
         storage: {
+            /** Bytes taken by stored files. */
             used: number;
+            /** Bytes free on the data volume. */
             available: number;
+            /** Usable size of the data volume, which other data may share. */
+            capacity?: number;
         };
         types: {
             mimeType: string;
@@ -1160,6 +1222,20 @@ type Stats = {
         }[];
         largest: FileWithUrl[];
         recent: FileWithUrl[];
+        /** Files and bytes per visibility. */
+        visibility?: Record<Visibility, {
+            count: number;
+            size: number;
+        }>;
+        /**
+         * Files added per UTC day over the last 30 days, oldest first. Only files
+         * still stored count, so deleting a file removes it from its day.
+         */
+        added?: {
+            date: string;
+            count: number;
+            size: number;
+        }[];
     } | null;
     /** Present for signed-in users holding `api-keys:manage`. */
     apiKeys: {
@@ -1169,7 +1245,36 @@ type Stats = {
             date: string;
             count: number;
         }[];
+        /**
+         * Every key with its requests over the same days, busiest first. Requests
+         * made with keys deleted since count in `requests` but in no key here.
+         */
+        keys?: ApiKeyUsage[];
     } | null;
+    /**
+     * Public hosting traffic over the last 30 UTC days. Present when the caller
+     * holds `files:read`. Requests made from a signed-in dashboard or app
+     * session aren't counted.
+     */
+    hosting?: {
+        /** Oldest first. */
+        days: TrafficDay[];
+        /** The five files requested most over those days. */
+        top: {
+            file: FileWithUrl;
+            requests: number;
+            bytes: number;
+        }[];
+    } | null;
+    /** Present for signed-in users holding `users:manage`. */
+    users?: {
+        total: number;
+        disabled: number;
+        /** Devices signed in across every account. */
+        sessions: number;
+    } | null;
+    /** Empty when nothing needs attention. New types may be added later. */
+    alerts?: StatsAlert[];
 };
 
 /** The caller's activity history. These calls need a session, not a key. */
@@ -1569,36 +1674,7 @@ declare class Vaze extends Base implements IVaze {
     /** The caller's account and the scopes it may use. */
     me(): Promise<ApiResponse<Me>>;
     /** Dashboard numbers, with each section limited to the caller's scopes. */
-    stats(): Promise<{
-        error: {
-            message: string;
-            status?: number;
-        } | null;
-        data: {
-            files: {
-                largest: any[];
-                recent: any[];
-                total: number;
-                folders: number;
-                storage: {
-                    used: number;
-                    available: number;
-                };
-                types: {
-                    mimeType: string;
-                    size: number;
-                    count: number;
-                }[];
-            } | null;
-            apiKeys: {
-                total: number;
-                requests: {
-                    date: string;
-                    count: number;
-                }[];
-            } | null;
-        } | null;
-    }>;
+    stats(): Promise<ApiResponse<Stats>>;
 }
 
-export { type ActivityEntry as Activity, type ActivityType, type ApiKeySummary as ApiKey, type ApiResponse, type BulkDeleteResult, type BulkMoveResult, type CreatedApiKey, type FileWithUrl as File, type FileReference, type Folder, type InstanceSettings, type Limits, type ListOptions, type Me, type MoveDestination, type NewKeyOptions, type NewUserOptions, type PasswordChange, type ProfileChanges, type Role, type Scope, type SessionSummary as Session, type SettingsChanges, type SignOptions, type SignedUrl, type Stats, type UserSummary as User, type UserAccess, type VazeHeaders, type VazeOptions, type Visibility, Vaze as default };
+export { type ActivityEntry as Activity, type ActivityType, type ApiKeySummary as ApiKey, type ApiKeyUsage, type ApiResponse, type BulkDeleteResult, type BulkMoveResult, type CreatedApiKey, type FileWithUrl as File, type FileReference, type Folder, type InstanceSettings, type Limits, type ListOptions, type Me, type MoveDestination, type NewKeyOptions, type NewUserOptions, type PasswordChange, type ProfileChanges, type Role, type Scope, type SessionSummary as Session, type SettingsChanges, type SignOptions, type SignedUrl, type Stats, type StatsAlert, type TrafficDay, type UserSummary as User, type UserAccess, type VazeHeaders, type VazeOptions, type Visibility, Vaze as default };

package/dist/index.d.ts

@@ -1144,14 +1144,76 @@ type InstanceSettings = {
     visibilityCounts: Record<Visibility, number>;
     limits: Limits;
 };
+/** One API key's share of the week's requests. */
+type ApiKeyUsage = {
+    id: string;
+    name: string;
+    /** Requests over the same seven UTC days as `Stats["apiKeys"]["requests"]`. */
+    requests: number;
+    lastUsed: string | null;
+    expiresAt: string | null;
+};
+/** Public hosting traffic for one UTC day. */
+type TrafficDay = {
+    date: string;
+    /** Responses that served a file: 200, 206 and 304. */
+    requests: number;
+    /** Body bytes streamed out. */
+    bytes: number;
+    /** Requests for keys that matched no file the caller could read. */
+    notFound: number;
+};
+/** Something on the instance worth acting on. */
+type StatsAlert = 
+/** The data volume has less than a tenth of its space left. */
+{
+    type: "storage-low";
+    available: number;
+    capacity: number;
+}
+/** The caller's own uploads that failed over the last seven days. */
+ | {
+    type: "uploads-failed";
+    count: number;
+    latest: string;
+}
+/** The caller's own file and folder deletes that failed over the last seven days. */
+ | {
+    type: "deletes-failed";
+    count: number;
+    latest: string;
+}
+/** The caller's keys past their expiry date, which no longer work. */
+ | {
+    type: "keys-expired";
+    count: number;
+}
+/** The caller's keys that expire within seven days. */
+ | {
+    type: "keys-expiring";
+    count: number;
+}
+/** The caller's keys not used for 30 days. */
+ | {
+    type: "keys-unused";
+    count: number;
+};
+/**
+ * Fields marked optional were added after the first release of this endpoint.
+ * Servers that predate them leave them out, so check before reading.
+ */
 type Stats = {
     /** Present when the caller holds `files:read`. */
     files: {
         total: number;
         folders: number;
         storage: {
+            /** Bytes taken by stored files. */
             used: number;
+            /** Bytes free on the data volume. */
             available: number;
+            /** Usable size of the data volume, which other data may share. */
+            capacity?: number;
         };
         types: {
             mimeType: string;
@@ -1160,6 +1222,20 @@ type Stats = {
         }[];
         largest: FileWithUrl[];
         recent: FileWithUrl[];
+        /** Files and bytes per visibility. */
+        visibility?: Record<Visibility, {
+            count: number;
+            size: number;
+        }>;
+        /**
+         * Files added per UTC day over the last 30 days, oldest first. Only files
+         * still stored count, so deleting a file removes it from its day.
+         */
+        added?: {
+            date: string;
+            count: number;
+            size: number;
+        }[];
     } | null;
     /** Present for signed-in users holding `api-keys:manage`. */
     apiKeys: {
@@ -1169,7 +1245,36 @@ type Stats = {
             date: string;
             count: number;
         }[];
+        /**
+         * Every key with its requests over the same days, busiest first. Requests
+         * made with keys deleted since count in `requests` but in no key here.
+         */
+        keys?: ApiKeyUsage[];
     } | null;
+    /**
+     * Public hosting traffic over the last 30 UTC days. Present when the caller
+     * holds `files:read`. Requests made from a signed-in dashboard or app
+     * session aren't counted.
+     */
+    hosting?: {
+        /** Oldest first. */
+        days: TrafficDay[];
+        /** The five files requested most over those days. */
+        top: {
+            file: FileWithUrl;
+            requests: number;
+            bytes: number;
+        }[];
+    } | null;
+    /** Present for signed-in users holding `users:manage`. */
+    users?: {
+        total: number;
+        disabled: number;
+        /** Devices signed in across every account. */
+        sessions: number;
+    } | null;
+    /** Empty when nothing needs attention. New types may be added later. */
+    alerts?: StatsAlert[];
 };
 
 /** The caller's activity history. These calls need a session, not a key. */
@@ -1569,36 +1674,7 @@ declare class Vaze extends Base implements IVaze {
     /** The caller's account and the scopes it may use. */
     me(): Promise<ApiResponse<Me>>;
     /** Dashboard numbers, with each section limited to the caller's scopes. */
-    stats(): Promise<{
-        error: {
-            message: string;
-            status?: number;
-        } | null;
-        data: {
-            files: {
-                largest: any[];
-                recent: any[];
-                total: number;
-                folders: number;
-                storage: {
-                    used: number;
-                    available: number;
-                };
-                types: {
-                    mimeType: string;
-                    size: number;
-                    count: number;
-                }[];
-            } | null;
-            apiKeys: {
-                total: number;
-                requests: {
-                    date: string;
-                    count: number;
-                }[];
-            } | null;
-        } | null;
-    }>;
+    stats(): Promise<ApiResponse<Stats>>;
 }
 
-export { type ActivityEntry as Activity, type ActivityType, type ApiKeySummary as ApiKey, type ApiResponse, type BulkDeleteResult, type BulkMoveResult, type CreatedApiKey, type FileWithUrl as File, type FileReference, type Folder, type InstanceSettings, type Limits, type ListOptions, type Me, type MoveDestination, type NewKeyOptions, type NewUserOptions, type PasswordChange, type ProfileChanges, type Role, type Scope, type SessionSummary as Session, type SettingsChanges, type SignOptions, type SignedUrl, type Stats, type UserSummary as User, type UserAccess, type VazeHeaders, type VazeOptions, type Visibility, Vaze as default };
+export { type ActivityEntry as Activity, type ActivityType, type ApiKeySummary as ApiKey, type ApiKeyUsage, type ApiResponse, type BulkDeleteResult, type BulkMoveResult, type CreatedApiKey, type FileWithUrl as File, type FileReference, type Folder, type InstanceSettings, type Limits, type ListOptions, type Me, type MoveDestination, type NewKeyOptions, type NewUserOptions, type PasswordChange, type ProfileChanges, type Role, type Scope, type SessionSummary as Session, type SettingsChanges, type SignOptions, type SignedUrl, type Stats, type StatsAlert, type TrafficDay, type UserSummary as User, type UserAccess, type VazeHeaders, type VazeOptions, type Visibility, Vaze as default };

package/dist/index.js

@@ -606,27 +606,37 @@ var Vaze = class extends Base {
   }
   /** Dashboard numbers, with each section limited to the caller's scopes. */
   async stats() {
-    const { data, error } = await this.request(
+    const response = await this.request(
       "GET",
       this.apiUrl("/api/stats")
     );
-    const files = data?.files;
+    if (response.data === null) return response;
+    const { files, hosting } = response.data;
+    const vazeUrl = this.vazeUrl;
+    const withUrl = (file) => ({
+      ...file,
+      url: constructFileUrls({ vazeUrl, files: [file] })[0].url
+    });
     return {
-      error,
-      data: data ? {
-        ...data,
+      error: null,
+      data: {
+        ...response.data,
         files: files ? {
           ...files,
-          largest: constructFileUrls({
-            vazeUrl: this.vazeUrl,
-            files: files.largest
-          }),
-          recent: constructFileUrls({
-            vazeUrl: this.vazeUrl,
-            files: files.recent
-          })
-        } : null
-      } : null
+          largest: constructFileUrls({ vazeUrl, files: files.largest }),
+          recent: constructFileUrls({ vazeUrl, files: files.recent })
+        } : null,
+        // servers that predate traffic leave `hosting` out, so keep it out
+        ...hosting ? {
+          hosting: {
+            ...hosting,
+            top: hosting.top.map((entry) => ({
+              ...entry,
+              file: withUrl(entry.file)
+            }))
+          }
+        } : {}
+      }
     };
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darseen/vaze",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Vaze Self-Hosted file storage and hosting service SDK.",
   "keywords": [
     "api",
@@ -12,7 +12,7 @@
     "file-storage",
     "vaze"
   ],
-  "homepage": "https://github.com/darseen/vaze#readme",
+  "homepage": "https://vaze.darseen.dev/docs/sdk",
   "bugs": {
     "url": "https://github.com/darseen/vaze/issues"
   },