@darseen/vaze 2.5.0 → 2.7.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
@@ -147,10 +149,11 @@ const { data, error } = await vaze.files.rename({
 });
 ```
 
-`delete(id)` Delete a file by its ID.
+`delete(id, options?)` Delete a file by its ID. It moves to Recently deleted, where it can be restored until it is purged. Pass `{ permanent: true }` to remove it from storage right away. `deleteMany(ids, options?)` does the same for several files.
 
 ```ts
 const { data, error } = await vaze.files.delete("file-id-123");
+await vaze.files.delete("file-id-456", { permanent: true });
 ```
 
 Folders API Access folder-related methods via `vaze.folders`. `get(options?)` Retrieve folders and their contents.
@@ -207,12 +210,21 @@ if (data) {
 }
 ```
 
-`delete(id)` Delete a folder by its ID.
+`delete(id, options?)` Delete a folder by its ID. It moves to Recently deleted with everything inside it, unless you pass `{ permanent: true }`.
 
 ```ts
 const { data, error } = await vaze.folders.delete("folder-id");
 ```
 
+Recently Deleted API Restore or purge deleted files and folders via `vaze.deleted`. Listing needs `files:read`, and restoring and purging need `files:delete`. Items are purged on their own once they are older than the instance's `deletedRetentionDays`.
+
+```ts
+const { data } = await vaze.deleted.getAll(); // items, newest first, and retentionDays
+await vaze.deleted.restore(["file-id-123", "folder-id"]); // back where they were
+await vaze.deleted.purge(["file-id-456"]); // gone for good
+await vaze.deleted.empty();
+```
+
 Keys API Manage the caller's API keys via `vaze.keys`. These calls need a client that acts as a signed-in user (`headers`) holding `api-keys:manage`; a client built with an API key gets a `403`.
 
 `getAll()` List the caller's keys, newest first.
@@ -301,7 +313,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 +324,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`, `DeletedItem`, `ApiKey`, `Activity`, `User`, `Session`, `InstanceSettings`, `Stats`, `StatsAlert`, `TrafficDay`, `ApiKeyUsage`, `ApiResponse`, `ListOptions`, and `VazeOptions`.

package/dist/index.cjs

@@ -218,6 +218,41 @@ var Activity = class extends Base {
   }
 };
 
+// src/deleted.ts
+var Deleted = class extends Base {
+  /** Most recently deleted first, with how many days items are kept. */
+  async getAll() {
+    return await this.request(
+      "GET",
+      this.apiUrl("/api/deleted")
+    );
+  }
+  /** Put items back where they were; one whose name is taken now fails. */
+  async restore(ids) {
+    return await this.request(
+      "POST",
+      this.apiUrl("/api/deleted/restore"),
+      { ids }
+    );
+  }
+  /** Delete items for good, before their time is up. */
+  async purge(ids) {
+    return await this.request(
+      "DELETE",
+      this.apiUrl("/api/deleted"),
+      { ids }
+    );
+  }
+  /** Delete everything in it for good. */
+  async empty() {
+    return await this.request(
+      "DELETE",
+      this.apiUrl("/api/deleted"),
+      { all: true }
+    );
+  }
+};
+
 // src/files.ts
 var Files = class extends Base {
   async getAll(options) {
@@ -384,17 +419,19 @@ var Files = class extends Base {
       data: data ? { ...data, url: new URL(data.url, this.vazeUrl).toString() } : null
     };
   }
-  async delete(id) {
+  /** Moves the file to Recently deleted, unless `permanent` is set. */
+  async delete(id, options) {
     return await this.request("DELETE", this.apiUrl("/api/files"), {
-      id
+      id,
+      ...options
     });
   }
   /** Delete several files in one request; each id reports its own outcome. */
-  async deleteMany(ids) {
+  async deleteMany(ids, options) {
     return await this.request(
       "DELETE",
       this.apiUrl("/api/files"),
-      { ids }
+      { ids, ...options }
     );
   }
 };
@@ -445,9 +482,11 @@ var Folders = class extends Base {
   async setVisibility(data) {
     return await this.request("PUT", this.apiUrl("/api/folders"), data);
   }
-  async delete(id) {
+  /** Moves the folder and everything in it to Recently deleted, unless `permanent` is set. */
+  async delete(id, options) {
     return await this.request("DELETE", this.apiUrl("/api/folders"), {
-      id
+      id,
+      ...options
     });
   }
 };
@@ -577,10 +616,12 @@ var Vaze = class extends Base {
   
   
   
+  
   constructor(options = {}) {
     super(options);
     this.files = new Files(options);
     this.folders = new Folders(options);
+    this.deleted = new Deleted(options);
     this.keys = new Keys(options);
     this.account = new Account(options);
     this.activity = new Activity(options);
@@ -606,27 +647,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

@@ -941,6 +941,25 @@ declare const files: SQLiteTableWithColumns<{
         }, {}, {
             length: number | undefined;
         }>;
+        deletedAt: SQLiteColumn<{
+            name: "deleted_at";
+            tableName: "files";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;
@@ -1065,6 +1084,25 @@ declare const folders: SQLiteTableWithColumns<{
         }, {}, {
             length: number | undefined;
         }>;
+        deletedAt: SQLiteColumn<{
+            name: "deleted_at";
+            tableName: "folders";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;
@@ -1136,6 +1174,8 @@ type Limits = {
     hostingCacheMaxAge: number;
     activityRetentionDays: number;
     apiRequestRetentionDays: number;
+    /** Days a deleted file or folder can be restored before it is purged. */
+    deletedRetentionDays: number;
 };
 type InstanceSettings = {
     /** Applied to uploads and new folders that don't ask for one. */
@@ -1144,14 +1184,97 @@ type InstanceSettings = {
     visibilityCounts: Record<Visibility, number>;
     limits: Limits;
 };
+/** A file or folder in Recently deleted, which a restore puts back at `key`. */
+type DeletedItem = {
+    id: string;
+    name: string;
+    /** Where it was; a restore recreates any folders on the way that are gone. */
+    key: string;
+    /** Bytes it holds, everything inside it for a folder. */
+    size: number;
+    deletedAt: string;
+    /** When it is deleted for good, unless restored first. */
+    purgeAt: string;
+} & ({
+    type: "file";
+    mimeType: string;
+} | {
+    type: "folder";
+    /** Files anywhere inside it. */
+    files: number;
+});
+/** 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`. */
+    /** Present when the caller holds `files:read`. Files in Recently deleted aren't counted. */
     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;
+            /** Bytes held by files in Recently deleted, not counted in `used`. */
+            deleted?: number;
         };
         types: {
             mimeType: string;
@@ -1160,6 +1283,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 +1306,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. */
@@ -1187,6 +1353,21 @@ declare class Activity extends Base {
     }>>;
 }
 
+/** Files and folders that were deleted and can still be restored. */
+declare class Deleted extends Base {
+    /** Most recently deleted first, with how many days items are kept. */
+    getAll(): Promise<ApiResponse<{
+        items: DeletedItem[];
+        retentionDays: number;
+    }>>;
+    /** Put items back where they were; one whose name is taken now fails. */
+    restore(ids: string[]): Promise<ApiResponse<BulkRestoreResult>>;
+    /** Delete items for good, before their time is up. */
+    purge(ids: string[]): Promise<ApiResponse<BulkDeleteResult>>;
+    /** Delete everything in it for good. */
+    empty(): Promise<ApiResponse<BulkDeleteResult>>;
+}
+
 declare class Files extends Base {
     getAll(options?: ListOptions): Promise<{
         error: {
@@ -1303,9 +1484,10 @@ declare class Files extends Base {
             expiresAt: string;
         } | null;
     }>;
-    delete(id: string): Promise<ApiResponse<null>>;
+    /** Moves the file to Recently deleted, unless `permanent` is set. */
+    delete(id: string, options?: DeleteOptions): Promise<ApiResponse<null>>;
     /** Delete several files in one request; each id reports its own outcome. */
-    deleteMany(ids: string[]): Promise<ApiResponse<BulkDeleteResult>>;
+    deleteMany(ids: string[], options?: DeleteOptions): Promise<ApiResponse<BulkDeleteResult>>;
 }
 
 declare class Folders extends Base {
@@ -1355,7 +1537,8 @@ declare class Folders extends Base {
         id: string;
         visibility: Visibility;
     }): Promise<ApiResponse<null>>;
-    delete(id: string): Promise<ApiResponse<null>>;
+    /** Moves the folder and everything in it to Recently deleted, unless `permanent` is set. */
+    delete(id: string, options?: DeleteOptions): Promise<ApiResponse<null>>;
 }
 
 /** The caller's API keys. These calls need a signed-in session, not a key. */
@@ -1423,6 +1606,7 @@ declare class Users extends Base {
 interface IVaze {
     files: Files;
     folders: Folders;
+    deleted: Deleted;
     keys: Keys;
     account: Account;
     activity: Activity;
@@ -1517,6 +1701,17 @@ type BulkDeleteResult = {
         message: string;
     }[];
 };
+type BulkRestoreResult = {
+    restored: string[];
+    failed: {
+        id: string;
+        message: string;
+    }[];
+};
+type DeleteOptions = {
+    /** Skip Recently deleted and remove it from storage right away. */
+    permanent?: boolean;
+};
 
 declare class Base {
     private apiKey;
@@ -1553,6 +1748,7 @@ declare class Account extends Base {
 declare class Vaze extends Base implements IVaze {
     files: Files;
     folders: Folders;
+    deleted: Deleted;
     keys: Keys;
     account: Account;
     activity: Activity;
@@ -1569,36 +1765,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 BulkRestoreResult, type CreatedApiKey, type DeleteOptions, type DeletedItem, 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

@@ -941,6 +941,25 @@ declare const files: SQLiteTableWithColumns<{
         }, {}, {
             length: number | undefined;
         }>;
+        deletedAt: SQLiteColumn<{
+            name: "deleted_at";
+            tableName: "files";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;
@@ -1065,6 +1084,25 @@ declare const folders: SQLiteTableWithColumns<{
         }, {}, {
             length: number | undefined;
         }>;
+        deletedAt: SQLiteColumn<{
+            name: "deleted_at";
+            tableName: "folders";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;
@@ -1136,6 +1174,8 @@ type Limits = {
     hostingCacheMaxAge: number;
     activityRetentionDays: number;
     apiRequestRetentionDays: number;
+    /** Days a deleted file or folder can be restored before it is purged. */
+    deletedRetentionDays: number;
 };
 type InstanceSettings = {
     /** Applied to uploads and new folders that don't ask for one. */
@@ -1144,14 +1184,97 @@ type InstanceSettings = {
     visibilityCounts: Record<Visibility, number>;
     limits: Limits;
 };
+/** A file or folder in Recently deleted, which a restore puts back at `key`. */
+type DeletedItem = {
+    id: string;
+    name: string;
+    /** Where it was; a restore recreates any folders on the way that are gone. */
+    key: string;
+    /** Bytes it holds, everything inside it for a folder. */
+    size: number;
+    deletedAt: string;
+    /** When it is deleted for good, unless restored first. */
+    purgeAt: string;
+} & ({
+    type: "file";
+    mimeType: string;
+} | {
+    type: "folder";
+    /** Files anywhere inside it. */
+    files: number;
+});
+/** 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`. */
+    /** Present when the caller holds `files:read`. Files in Recently deleted aren't counted. */
     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;
+            /** Bytes held by files in Recently deleted, not counted in `used`. */
+            deleted?: number;
         };
         types: {
             mimeType: string;
@@ -1160,6 +1283,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 +1306,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. */
@@ -1187,6 +1353,21 @@ declare class Activity extends Base {
     }>>;
 }
 
+/** Files and folders that were deleted and can still be restored. */
+declare class Deleted extends Base {
+    /** Most recently deleted first, with how many days items are kept. */
+    getAll(): Promise<ApiResponse<{
+        items: DeletedItem[];
+        retentionDays: number;
+    }>>;
+    /** Put items back where they were; one whose name is taken now fails. */
+    restore(ids: string[]): Promise<ApiResponse<BulkRestoreResult>>;
+    /** Delete items for good, before their time is up. */
+    purge(ids: string[]): Promise<ApiResponse<BulkDeleteResult>>;
+    /** Delete everything in it for good. */
+    empty(): Promise<ApiResponse<BulkDeleteResult>>;
+}
+
 declare class Files extends Base {
     getAll(options?: ListOptions): Promise<{
         error: {
@@ -1303,9 +1484,10 @@ declare class Files extends Base {
             expiresAt: string;
         } | null;
     }>;
-    delete(id: string): Promise<ApiResponse<null>>;
+    /** Moves the file to Recently deleted, unless `permanent` is set. */
+    delete(id: string, options?: DeleteOptions): Promise<ApiResponse<null>>;
     /** Delete several files in one request; each id reports its own outcome. */
-    deleteMany(ids: string[]): Promise<ApiResponse<BulkDeleteResult>>;
+    deleteMany(ids: string[], options?: DeleteOptions): Promise<ApiResponse<BulkDeleteResult>>;
 }
 
 declare class Folders extends Base {
@@ -1355,7 +1537,8 @@ declare class Folders extends Base {
         id: string;
         visibility: Visibility;
     }): Promise<ApiResponse<null>>;
-    delete(id: string): Promise<ApiResponse<null>>;
+    /** Moves the folder and everything in it to Recently deleted, unless `permanent` is set. */
+    delete(id: string, options?: DeleteOptions): Promise<ApiResponse<null>>;
 }
 
 /** The caller's API keys. These calls need a signed-in session, not a key. */
@@ -1423,6 +1606,7 @@ declare class Users extends Base {
 interface IVaze {
     files: Files;
     folders: Folders;
+    deleted: Deleted;
     keys: Keys;
     account: Account;
     activity: Activity;
@@ -1517,6 +1701,17 @@ type BulkDeleteResult = {
         message: string;
     }[];
 };
+type BulkRestoreResult = {
+    restored: string[];
+    failed: {
+        id: string;
+        message: string;
+    }[];
+};
+type DeleteOptions = {
+    /** Skip Recently deleted and remove it from storage right away. */
+    permanent?: boolean;
+};
 
 declare class Base {
     private apiKey;
@@ -1553,6 +1748,7 @@ declare class Account extends Base {
 declare class Vaze extends Base implements IVaze {
     files: Files;
     folders: Folders;
+    deleted: Deleted;
     keys: Keys;
     account: Account;
     activity: Activity;
@@ -1569,36 +1765,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 BulkRestoreResult, type CreatedApiKey, type DeleteOptions, type DeletedItem, 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

@@ -218,6 +218,41 @@ var Activity = class extends Base {
   }
 };
 
+// src/deleted.ts
+var Deleted = class extends Base {
+  /** Most recently deleted first, with how many days items are kept. */
+  async getAll() {
+    return await this.request(
+      "GET",
+      this.apiUrl("/api/deleted")
+    );
+  }
+  /** Put items back where they were; one whose name is taken now fails. */
+  async restore(ids) {
+    return await this.request(
+      "POST",
+      this.apiUrl("/api/deleted/restore"),
+      { ids }
+    );
+  }
+  /** Delete items for good, before their time is up. */
+  async purge(ids) {
+    return await this.request(
+      "DELETE",
+      this.apiUrl("/api/deleted"),
+      { ids }
+    );
+  }
+  /** Delete everything in it for good. */
+  async empty() {
+    return await this.request(
+      "DELETE",
+      this.apiUrl("/api/deleted"),
+      { all: true }
+    );
+  }
+};
+
 // src/files.ts
 var Files = class extends Base {
   async getAll(options) {
@@ -384,17 +419,19 @@ var Files = class extends Base {
       data: data ? { ...data, url: new URL(data.url, this.vazeUrl).toString() } : null
     };
   }
-  async delete(id) {
+  /** Moves the file to Recently deleted, unless `permanent` is set. */
+  async delete(id, options) {
     return await this.request("DELETE", this.apiUrl("/api/files"), {
-      id
+      id,
+      ...options
     });
   }
   /** Delete several files in one request; each id reports its own outcome. */
-  async deleteMany(ids) {
+  async deleteMany(ids, options) {
     return await this.request(
       "DELETE",
       this.apiUrl("/api/files"),
-      { ids }
+      { ids, ...options }
     );
   }
 };
@@ -445,9 +482,11 @@ var Folders = class extends Base {
   async setVisibility(data) {
     return await this.request("PUT", this.apiUrl("/api/folders"), data);
   }
-  async delete(id) {
+  /** Moves the folder and everything in it to Recently deleted, unless `permanent` is set. */
+  async delete(id, options) {
     return await this.request("DELETE", this.apiUrl("/api/folders"), {
-      id
+      id,
+      ...options
     });
   }
 };
@@ -572,6 +611,7 @@ var Users = class extends Base {
 var Vaze = class extends Base {
   files;
   folders;
+  deleted;
   keys;
   account;
   activity;
@@ -581,6 +621,7 @@ var Vaze = class extends Base {
     super(options);
     this.files = new Files(options);
     this.folders = new Folders(options);
+    this.deleted = new Deleted(options);
     this.keys = new Keys(options);
     this.account = new Account(options);
     this.activity = new Activity(options);
@@ -606,27 +647,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.7.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"
   },