@darseen/vaze 2.3.0 → 2.5.0

package/README.md

@@ -37,6 +37,20 @@ const vaze = new Vaze({
 });
 ```
 
+# Acting as a Signed-in User
+
+Apps that sign people in can send their session instead of an API key. Pass `headers`, an object or a function called before every request, and an optional `fetch` to replace the global one:
+
+```ts
+const vaze = new Vaze({
+  vazeUrl: "http://your-server-ip:3000",
+  headers: async () => ({ cookie: await getSessionCookie() }),
+  fetch: (input, init) => fetch(input, { ...init, credentials: "omit" }),
+});
+```
+
+`vaze.authHeaders()` returns the headers the SDK sends, for clients that fetch an SDK URL themselves, such as `vaze.files.thumbnailUrl(id)` or `vaze.files.downloadUrl(id)`.
+
 # Using Environment Variables
 
 If you set `VAZE_URL` and `VAZE_API_KEY` in your environment, you can initialize the client without passing arguments:
@@ -50,7 +64,7 @@ const vaze = new Vaze();
 
 # API Documentation
 
-The SDK is divided into two main modules: `files` and `folders`. All methods are asynchronous and return a standard `ApiResponse` object containing either `data` or an `error`. Files API Access file-related methods via `vaze.files.getAll(options?)` Retrieve a paginated list of all files.
+The SDK's main modules are `files` and `folders`, plus `keys`, `account`, `activity`, `users` and `settings` for signed-in users. All methods are asynchronous and return a standard `ApiResponse` object containing either `data` or an `error`. Files API Access file-related methods via `vaze.files.getAll(options?)` Retrieve a paginated list of all files.
 
 - options (optional):
   - `limit`
@@ -87,7 +101,7 @@ const { data, error } = await vaze.files.getByName("document.pdf", {
 `upload(data)` Upload one or multiple files to your Vaze instance.
 
 - data:
-  - `files` (File[]): An array of standard web [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) objects.
+  - `files` (File[]): An array of standard web [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) objects, or in React Native, `{ uri, name, type }` references.
   - `folder?` (string): The path of the target folder, created if it doesn't exist.
 
 ```ts
@@ -199,6 +213,80 @@ if (data) {
 const { data, error } = await vaze.folders.delete("folder-id");
 ```
 
+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.
+
+```ts
+const { data, error } = await vaze.keys.getAll();
+```
+
+`create(options)` Create a key. The secret in `data.key.key` is only returned this once.
+
+- options:
+  - `name`: Unique among the caller's keys.
+  - `scopes`: Any of `files:read`, `files:write` and `files:delete` the caller holds.
+  - `expiresAt` (optional): A `Date` or ISO string; leave it out for a key that never expires.
+
+```ts
+const { data, error } = await vaze.keys.create({
+  name: "Backup script",
+  scopes: ["files:read", "files:write"],
+});
+
+console.log(data?.key.key); // "vz_..."
+```
+
+`rename(data)` Rename a key. Scopes and expiry can't change.
+
+```ts
+const { data, error } = await vaze.keys.rename({ id: "key-id", name: "Nightly backup" });
+```
+
+`delete(id)` Delete a key, which stops working right away.
+
+```ts
+const { data, error } = await vaze.keys.delete("key-id");
+```
+
+Account API Change the signed-in user's own account via `vaze.account`. These calls need a client that acts as a signed-in user (`headers`); a client built with an API key gets a `403`.
+
+```ts
+await vaze.account.update({ name: "Dana Scully", email: "dana@example.org" });
+await vaze.account.changePassword({ currentPassword: "old", newPassword: "new-password", revokeOtherSessions: true });
+
+const { data } = await vaze.account.getSessions(); // devices, the current one first
+await vaze.account.revokeSession("session-id");
+await vaze.account.revokeOtherSessions();
+```
+
+Activity API Read and prune the caller's history of uploads, deletions and changes via `vaze.activity`. Needs a signed-in user.
+
+```ts
+const { data } = await vaze.activity.getAll(); // the 200 most recent entries
+await vaze.activity.delete(["activity-id"]);
+await vaze.activity.clear();
+```
+
+Users API Manage accounts via `vaze.users`. Needs a signed-in admin (`users:manage`). None of the changes work on the caller's own account.
+
+```ts
+const { data } = await vaze.users.getAll();
+await vaze.users.create({ name: "Dana", email: "dana@example.com", password: "a-long-password", role: "viewer" });
+await vaze.users.setAccess({ id: "user-id", role: "custom", scopes: ["files:read"] });
+await vaze.users.resetPassword({ id: "user-id", password: "a-new-password" });
+await vaze.users.setDisabled({ id: "user-id", disabled: true });
+await vaze.users.delete("user-id");
+```
+
+Settings API Read and change instance-wide settings via `vaze.settings`. Needs a signed-in user holding `settings:manage`.
+
+```ts
+const { data } = await vaze.settings.get(); // defaultVisibility, visibilityCounts, limits
+await vaze.settings.update({ defaultVisibility: "private", limits: { activityRetentionDays: 30 } });
+await vaze.settings.applyVisibility("private"); // every existing file
+```
+
 # Health Check
 
 `vaze.health()` pings the instance to verify connectivity.
@@ -211,6 +299,17 @@ 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.
+
+```ts
+const { data } = await vaze.me();
+const canUpload = data?.scopes.includes("files:write");
+```
+
+Failed requests carry the HTTP status in `error.status`, such as `401` once a session expires.
+
 # Types
 
-This SDK is built with TypeScript and exports all necessary types to ensure type safety in your applications. Types such as `File`, `Folder`, `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`, `ApiResponse`, `ListOptions`, and `VazeOptions`.

package/dist/index.cjs

@@ -1,4 +1,7 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/utils/index.ts
+function env(name) {
+  return typeof process === "undefined" ? void 0 : _optionalChain([process, 'access', _ => _.env, 'optionalAccess', _2 => _2[name]]);
+}
 function constructFileUrls({
   vazeUrl,
   files
@@ -12,34 +15,39 @@ function constructFileUrls({
 function parseContentDispositionFilename(header) {
   if (!header) return null;
   const utf8Match = header.match(/filename\*=UTF-8''([^;]+)/i);
-  if (_optionalChain([utf8Match, 'optionalAccess', _ => _[1]])) {
+  if (_optionalChain([utf8Match, 'optionalAccess', _3 => _3[1]])) {
     try {
       return decodeURIComponent(utf8Match[1]);
     } catch (e) {
     }
   }
   const plainMatch = header.match(/filename="([^"]*)"/i);
-  return _nullishCoalesce(_optionalChain([plainMatch, 'optionalAccess', _2 => _2[1]]), () => ( null));
+  return _nullishCoalesce(_optionalChain([plainMatch, 'optionalAccess', _4 => _4[1]]), () => ( null));
 }
 
 // src/base.ts
 var Base = class {
   
   
+  // wrapped so the global fetch is never called with this class as `this`
+  
+  
   constructor(options = {}) {
-    const vazeUrl = options.vazeUrl || process.env.VAZE_URL;
-    const apiKey = options.apiKey || process.env.VAZE_API_KEY;
+    const vazeUrl = options.vazeUrl || env("VAZE_URL");
+    const apiKey = options.apiKey || env("VAZE_API_KEY");
     if (!vazeUrl) {
       throw new Error(
         "You must provide a Vaze URL or set the VAZE_URL environment variable."
       );
     }
-    if (!apiKey) {
+    if (!apiKey && !options.headers) {
       throw new Error(
-        "You must provide an API key or set the VAZE_API_KEY environment variable."
+        "You must provide an API key or headers, or set the VAZE_API_KEY environment variable."
       );
     }
     this.apiKey = apiKey;
+    this.headers = options.headers;
+    this.fetch = _nullishCoalesce(options.fetch, () => ( ((input, init) => fetch(input, init))));
     this.vazeUrl = vazeUrl.endsWith("/") ? vazeUrl : `${vazeUrl}/`;
   }
   apiUrl(path, params) {
@@ -51,35 +59,45 @@ var Base = class {
     }
     return url.toString();
   }
+  /** The headers every request carries, for clients fetching an SDK URL themselves. */
+  async authHeaders() {
+    const headers = typeof this.headers === "function" ? await this.headers() : this.headers;
+    return this.apiKey ? { ...headers, "API-Key": this.apiKey } : { ...headers };
+  }
   async request(method, url, body, headers) {
     try {
       const fetchHeaders = {
-        "API-Key": this.apiKey,
+        ...await this.authHeaders(),
         ...headers
       };
       const isFormData = body instanceof FormData;
       if (body !== void 0 && !isFormData && !fetchHeaders["Content-Type"]) {
         fetchHeaders["Content-Type"] = "application/json";
       }
-      const response = await fetch(url, {
+      const response = await this.fetch(url, {
         method,
         headers: fetchHeaders,
         body: isFormData ? body : body !== void 0 ? JSON.stringify(body) : null
       });
+      const { status } = response;
       const contentType = _nullishCoalesce(response.headers.get("content-type"), () => ( ""));
       if (!contentType.includes("application/json")) {
         return {
           data: null,
           error: {
-            message: `Unexpected non-JSON response from server (status ${response.status}).`
+            message: `Unexpected non-JSON response from server (status ${status}).`,
+            status
           }
         };
       }
       const result = await response.json();
-      if (!response.ok && !result.error) {
+      if (!response.ok) {
         return {
           data: null,
-          error: { message: `Request failed with status ${response.status}.` }
+          error: {
+            message: _nullishCoalesce(_optionalChain([result, 'access', _5 => _5.error, 'optionalAccess', _6 => _6.message]), () => ( `Request failed with status ${status}.`)),
+            status
+          }
         };
       }
       return result;
@@ -94,22 +112,25 @@ var Base = class {
   }
   async requestBlob(url, method = "GET", body) {
     try {
-      const headers = { "API-Key": this.apiKey };
+      const headers = await this.authHeaders();
       if (body !== void 0) headers["Content-Type"] = "application/json";
-      const response = await fetch(url, {
+      const response = await this.fetch(url, {
         method,
         headers,
         body: body !== void 0 ? JSON.stringify(body) : null
       });
+      const { status } = response;
       const contentType = _nullishCoalesce(response.headers.get("content-type"), () => ( ""));
       if (!response.ok) {
         if (contentType.includes("application/json")) {
           const result = await response.json();
-          if (result.error) return { data: null, error: result.error };
+          if (result.error) {
+            return { data: null, error: { ...result.error, status } };
+          }
         }
         return {
           data: null,
-          error: { message: `Request failed with status ${response.status}.` }
+          error: { message: `Request failed with status ${status}.`, status }
         };
       }
       return {
@@ -133,6 +154,70 @@ var Base = class {
   }
 };
 
+// src/account.ts
+var Account = class extends Base {
+  /** Changes the display name, the sign-in email, or both. */
+  async update(changes) {
+    return await this.request("PUT", this.apiUrl("/api/me"), changes);
+  }
+  async changePassword({
+    currentPassword,
+    newPassword,
+    revokeOtherSessions = false
+  }) {
+    return await this.request("PUT", this.apiUrl("/api/me/password"), {
+      currentPassword,
+      newPassword,
+      revokeOtherSessions
+    });
+  }
+  /** Every device signed in to the account, the current one first. */
+  async getSessions() {
+    return await this.request(
+      "GET",
+      this.apiUrl("/api/me/sessions")
+    );
+  }
+  /** Signs out another device. The current session ends with a sign-out instead. */
+  async revokeSession(id) {
+    return await this.request("DELETE", this.apiUrl("/api/me/sessions"), {
+      id
+    });
+  }
+  /** Signs out every device but the current one. */
+  async revokeOtherSessions() {
+    return await this.request("DELETE", this.apiUrl("/api/me/sessions"), {
+      others: true
+    });
+  }
+};
+
+// src/activity.ts
+var Activity = class extends Base {
+  /** The most recent entries, newest first. */
+  async getAll() {
+    return await this.request(
+      "GET",
+      this.apiUrl("/api/activity")
+    );
+  }
+  async delete(ids) {
+    return await this.request(
+      "DELETE",
+      this.apiUrl("/api/activity"),
+      { ids }
+    );
+  }
+  /** Deletes every entry. Files, keys and accounts are not affected. */
+  async clear() {
+    return await this.request(
+      "DELETE",
+      this.apiUrl("/api/activity"),
+      { all: true }
+    );
+  }
+};
+
 // src/files.ts
 var Files = class extends Base {
   async getAll(options) {
@@ -201,7 +286,7 @@ var Files = class extends Base {
   }
   async upload(data) {
     const { files, folder, visibility } = data;
-    const url = this.apiUrl("/api/files");
+    const url = this.uploadUrl();
     const formData = new FormData();
     if (folder) formData.append("folder", folder);
     if (visibility) formData.append("visibility", visibility);
@@ -219,15 +304,36 @@ var Files = class extends Base {
       } : null
     };
   }
+  /** Where `upload` posts its form, for upload managers that report progress. */
+  uploadUrl() {
+    return this.apiUrl("/api/files");
+  }
+  /** Record uploads canceled before they were sent, in the activity history. */
+  async reportCanceled(names) {
+    return await this.request(
+      "POST",
+      this.apiUrl("/api/files/canceled"),
+      { names }
+    );
+  }
   async download(id) {
-    const url = this.apiUrl(`/api/files/download/${encodeURIComponent(id)}`);
-    return await this.requestBlob(url);
+    return await this.requestBlob(this.downloadUrl(id));
+  }
+  /** Where `download` reads from; fetch it yourself with `authHeaders()`. */
+  downloadUrl(id) {
+    return this.apiUrl(`/api/files/download/${encodeURIComponent(id)}`);
+  }
+  /** A WebP thumbnail of an image file; fetch it with `authHeaders()`. */
+  thumbnailUrl(id) {
+    return this.apiUrl(`/api/files/thumbnail/${encodeURIComponent(id)}`);
   }
   /** Download several files as one zip, with paths below their shared folder. */
   async downloadMany(ids) {
-    return await this.requestBlob(this.apiUrl("/api/files/download"), "POST", {
-      ids
-    });
+    return await this.requestBlob(this.downloadManyUrl(), "POST", { ids });
+  }
+  /** Where `downloadMany` posts `{ ids }`; stream it yourself with `authHeaders()`. */
+  downloadManyUrl() {
+    return this.apiUrl("/api/files/download");
   }
   async rename(data) {
     return await this.request("PUT", this.apiUrl("/api/files"), data);
@@ -311,9 +417,11 @@ var Folders = class extends Base {
   }
   /** Download a folder and everything below it as a zip; the root by default. */
   async download(options) {
-    return await this.requestBlob(
-      this.apiUrl("/api/folders/download", options)
-    );
+    return await this.requestBlob(this.downloadUrl(options));
+  }
+  /** Where `download` reads from; fetch it yourself with `authHeaders()`. */
+  downloadUrl(options) {
+    return this.apiUrl("/api/folders/download", options);
   }
   async create(folder) {
     return await this.request(
@@ -344,14 +452,140 @@ var Folders = class extends Base {
   }
 };
 
+// src/keys.ts
+var Keys = class extends Base {
+  /** Every key the caller owns, newest first. */
+  async getAll() {
+    return await this.request(
+      "GET",
+      this.apiUrl("/api/keys")
+    );
+  }
+  /** The response holds the key's secret, which can't be read again later. */
+  async create({ name, scopes, expiresAt }) {
+    return await this.request(
+      "POST",
+      this.apiUrl("/api/keys"),
+      {
+        name,
+        scopes,
+        expiresAt: expiresAt instanceof Date ? expiresAt.toISOString() : expiresAt
+      }
+    );
+  }
+  async rename(data) {
+    return await this.request("PUT", this.apiUrl("/api/keys"), data);
+  }
+  /** Revokes the key at once for anything using it. */
+  async delete(id) {
+    return await this.request("DELETE", this.apiUrl("/api/keys"), {
+      id
+    });
+  }
+};
+
+// src/settings.ts
+var Settings = class extends Base {
+  async get() {
+    return await this.request(
+      "GET",
+      this.apiUrl("/api/settings")
+    );
+  }
+  /** Limits left out keep their current values. */
+  async update(changes) {
+    return await this.request(
+      "PUT",
+      this.apiUrl("/api/settings"),
+      changes
+    );
+  }
+  /** Gives every existing file this visibility. */
+  async applyVisibility(visibility) {
+    return await this.request(
+      "POST",
+      this.apiUrl("/api/settings/apply-visibility"),
+      { visibility }
+    );
+  }
+};
+
+// src/users.ts
+var Users = class extends Base {
+  /** Every account, oldest first. */
+  async getAll() {
+    return await this.request(
+      "GET",
+      this.apiUrl("/api/users")
+    );
+  }
+  async create(options) {
+    return await this.request(
+      "POST",
+      this.apiUrl("/api/users"),
+      options
+    );
+  }
+  /** Applies right away, to the user's sessions and API keys alike. */
+  async setAccess({
+    id,
+    role,
+    scopes = []
+  }) {
+    return await this.request(
+      "PUT",
+      this.apiUrl("/api/users"),
+      { id, role, scopes }
+    );
+  }
+  /** Also signs the user out of every device. */
+  async resetPassword({
+    id,
+    password
+  }) {
+    return await this.request(
+      "PUT",
+      this.apiUrl("/api/users"),
+      { id, password }
+    );
+  }
+  /** A disabled user is signed out and their API keys stop until re-enabled. */
+  async setDisabled({
+    id,
+    disabled
+  }) {
+    return await this.request(
+      "PUT",
+      this.apiUrl("/api/users"),
+      { id, disabled }
+    );
+  }
+  /** Removes the account, its API keys and its history. Files stay. */
+  async delete(id) {
+    return await this.request("DELETE", this.apiUrl("/api/users"), {
+      id
+    });
+  }
+};
+
 // src/index.ts
 var Vaze = class extends Base {
   
   
+  
+  
+  
+  
+  
   constructor(options = {}) {
     super(options);
     this.files = new Files(options);
     this.folders = new Folders(options);
+    this.keys = new Keys(options);
+    this.account = new Account(options);
+    this.activity = new Activity(options);
+    this.users = new Users(options);
+    this.settings = new Settings(options);
   }
   async health() {
     return await this.request(
@@ -359,6 +593,42 @@ var Vaze = class extends Base {
       this.apiUrl("/api/health")
     );
   }
+  /** Whether the instance still needs its first account, which becomes the admin. */
+  async setupStatus() {
+    return await this.request(
+      "GET",
+      this.apiUrl("/api/setup")
+    );
+  }
+  /** The caller's account and the scopes it may use. */
+  async me() {
+    return await this.request("GET", this.apiUrl("/api/me"));
+  }
+  /** Dashboard numbers, with each section limited to the caller's scopes. */
+  async stats() {
+    const { data, error } = await this.request(
+      "GET",
+      this.apiUrl("/api/stats")
+    );
+    const files = _optionalChain([data, 'optionalAccess', _7 => _7.files]);
+    return {
+      error,
+      data: data ? {
+        ...data,
+        files: files ? {
+          ...files,
+          largest: constructFileUrls({
+            vazeUrl: this.vazeUrl,
+            files: files.largest
+          }),
+          recent: constructFileUrls({
+            vazeUrl: this.vazeUrl,
+            files: files.recent
+          })
+        } : null
+      } : null
+    };
+  }
 };