@darseen/vaze 2.6.0 → 2.7.0

package/README.md

@@ -149,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.
@@ -209,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.
@@ -314,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`, `Stats`, `StatsAlert`, `TrafficDay`, `ApiKeyUsage`, `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);

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,6 +1184,25 @@ 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;
@@ -1203,7 +1262,7 @@ type StatsAlert =
  * 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;
@@ -1214,6 +1273,8 @@ type Stats = {
             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;
@@ -1292,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: {
@@ -1408,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 {
@@ -1460,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. */
@@ -1528,6 +1606,7 @@ declare class Users extends Base {
 interface IVaze {
     files: Files;
     folders: Folders;
+    deleted: Deleted;
     keys: Keys;
     account: Account;
     activity: Activity;
@@ -1622,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;
@@ -1658,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;
@@ -1677,4 +1768,4 @@ declare class Vaze extends Base implements IVaze {
     stats(): Promise<ApiResponse<Stats>>;
 }
 
-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 };
+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,6 +1184,25 @@ 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;
@@ -1203,7 +1262,7 @@ type StatsAlert =
  * 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;
@@ -1214,6 +1273,8 @@ type Stats = {
             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;
@@ -1292,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: {
@@ -1408,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 {
@@ -1460,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. */
@@ -1528,6 +1606,7 @@ declare class Users extends Base {
 interface IVaze {
     files: Files;
     folders: Folders;
+    deleted: Deleted;
     keys: Keys;
     account: Account;
     activity: Activity;
@@ -1622,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;
@@ -1658,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;
@@ -1677,4 +1768,4 @@ declare class Vaze extends Base implements IVaze {
     stats(): Promise<ApiResponse<Stats>>;
 }
 
-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 };
+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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darseen/vaze",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Vaze Self-Hosted file storage and hosting service SDK.",
   "keywords": [
     "api",