@meistrari/vault-sdk 0.0.12 → 1.0.0

package/dist/index.mjs

@@ -1,9 +1,20 @@
+import { GetUploadUrlResponseV2, GetDownloadUrlResponse } from '@meistrari/vault-shared/schemas';
+
 class FetchError extends Error {
-  constructor(message, response) {
+  constructor(message, url, method, response) {
     super(message);
+    this.message = message;
+    this.url = url;
+    this.method = method;
     this.response = response;
     this.name = "FetchError";
   }
+  static async from(url, method, response) {
+    const text = await response.clone().json().then((json) => JSON.stringify(json, null, 2)).catch(() => response.clone().text());
+    const error = new FetchError(`Failed to ${method} ${url}: ${response.status} ${response.statusText}:
+${text}`, url, method, response);
+    return error;
+  }
 }
 
 async function blobToBase64(blob) {
@@ -28,114 +39,348 @@ var __publicField$1 = (obj, key, value) => {
   __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
+const compatibilityDate = "2025-05-19";
+function removeVaultPrefix(url) {
+  return url.replace("vault://", "");
+}
+async function wrappedFetch(...params) {
+  const request = new Request(...params);
+  const response = await fetch(request);
+  if (!response.ok) {
+    throw await FetchError.from(request.url, request.method, response);
+  }
+  return response;
+}
 class VaultFile {
-  constructor(params) {
-    __publicField$1(this, "vaultUrl");
+  /**
+   * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended,
+   * instead use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
+   * or {@link VaultFile.fromContent} when preparing a new file for upload.
+   *
+   * @param params - The parameters for the VaultFile constructor
+   * @param params.config - The configuration for the VaultFile
+   * @param params.content - The content of the file
+   * @param params.id - The ID of the file
+   * @param params.name - The name of the file
+   * @param params.metadata - The metadata of the file
+   */
+  constructor({ config, content, id, name, metadata }) {
+    __publicField$1(this, "id");
     __publicField$1(this, "name");
-    __publicField$1(this, "headers");
-    this.name = params.name;
-    this.vaultUrl = params.vaultUrl;
-    this.headers = params.authStrategy.getHeaders();
-  }
-  getVaultUrl() {
-    if (this.name.includes("vault://")) {
-      return this.name;
-    }
-    return `vault://${this.name}`;
+    __publicField$1(this, "metadata");
+    __publicField$1(this, "config");
+    __publicField$1(this, "content");
+    __publicField$1(this, "lastDownloadUrl");
+    __publicField$1(this, "lastUploadUrl");
+    this.config = config;
+    this.content = content;
+    this.id = id;
+    this.name = name;
+    this.metadata = metadata;
   }
-  removeVaultPrefix(url) {
-    return url.replace("vault://", "");
-  }
-  async getUploadUrl() {
-    const response = await this._fetch({
-      method: "POST",
-      path: `/v2/files/${this.removeVaultPrefix(this.name)}`
-    });
-    return new URL(response.url);
-  }
-  async getDownloadUrl() {
-    const response = await this._fetch({
-      method: "GET",
-      path: `/v2/files/${this.removeVaultPrefix(this.name)}`
-    });
-    return new URL(response.url);
-  }
-  refreshAuth(authStrategy) {
-    this.headers = authStrategy.getHeaders();
+  /**
+   * Gets the headers for the request based on the auth strategy.
+   *
+   * @returns The headers for the request
+   */
+  get headers() {
+    return this.config.authStrategy.getHeaders();
   }
+  /**
+   * Performs a request to the vault service and handles the response or errors.
+   *
+   * @param params - The parameters for the fetch
+   * @param params.method - The method to use for the fetch
+   * @param params.path - The path to fetch
+   * @param params.body - The body of the request
+   * @returns The response from the vault
+   * @throws {FetchError} If the fetch fails
+   */
   async _fetch(params) {
-    const { method, path, body, ignoreHeaders } = params;
-    const url = new URL(this.vaultUrl + path).toString();
-    const response = await fetch(url, {
+    const { method, path, body } = params;
+    const url = new URL(this.config.vaultUrl + path).toString();
+    const headers = new Headers(this.headers);
+    headers.set("x-compatibility-date", compatibilityDate);
+    const response = await wrappedFetch(url, {
       method,
       body,
-      headers: ignoreHeaders ? void 0 : this.headers
+      headers
     });
-    if (!response.ok) {
-      throw new FetchError(`Failed to ${method} ${url}: ${response.status} ${response.statusText}`, response);
-    }
     const content = await response.json();
     return content;
   }
   /**
-   * Adds a SHA-256 hash of the file content as a prefix to the filename. This ensures uniqueness and prevents
-   * files with identical names but different content from overwriting each other in the vault.
+   * Creates a new file in the vault.
+   *
+   * @returns The metadata of the file
+   * @throws {Error} If the file ID is not set
+   * @throws {FetchError} If the metadata fetch fails
+   */
+  async _createFile() {
+    const response = await this._fetch({
+      method: "POST",
+      path: `/v2/files`,
+      body: JSON.stringify({
+        fileName: this.name,
+        sha256sum: this.id ?? this.metadata?.id ?? (this.content ? await getFileHash(this.content) : void 0)
+      })
+    }).then((data) => GetUploadUrlResponseV2.safeParse(data));
+    if (!response.success) {
+      throw new Error(`Invalid response from vault service. ${JSON.stringify(response.error)}`);
+    }
+    this.id = response.data.id;
+    this.metadata = response.data.metadata;
+    this.name = response.data.metadata?.originalFileName;
+    return response.data;
+  }
+  /**
+   * Creates a new VaultFile instance from a vault reference.
    *
-   * The resulting filename format is: "{hash}-{originalName}"
+   * @param params - The parameters for creating a VaultFile from a vault reference
+   * @param params.reference - The reference to the file in the vault
+   * @param params.config - The configuration for the VaultFile
+   * @param params.download - Whether to download the file content (default: false)
+   * @returns A new VaultFile instance
    *
-   * IMPORTANT: The modified filename must be stored and used for all future operations with this file in the vault,
-   * as it becomes the file's unique identifier. The original filename alone will not be sufficient to retrieve
-   * the file later.
+   * @example
+   * ```ts
+   * // Lazily download the file content
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://1234567890',
+   *     config: {
+   *         vaultUrl,
+   *         authStrategy,
+   *     }
+   * })
+   * const content = await vaultFile.download()
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Download the file content while creating the instance
+   * const vaultFile = await VaultFile.fromVaultReference({
+   *     reference: 'vault://1234567890',
+   *     config: {
+   *         vaultUrl,
+   *         authStrategy,
+   *     },
+   *     download: true
+   * })
+   * const content = vaultFile.content
+   * ```
+   */
+  static async fromVaultReference(params) {
+    const { reference, config, download = false } = params;
+    const { vaultUrl, authStrategy } = config;
+    const id = removeVaultPrefix(reference);
+    const response = await wrappedFetch(`${vaultUrl}/v2/files/${id}`, {
+      method: "GET",
+      headers: authStrategy.getHeaders()
+    }).then((response2) => response2.json()).then((data) => GetDownloadUrlResponse.safeParse(data));
+    if (!response.success) {
+      throw new Error("Invalid response from vault service");
+    }
+    const fileParams = {
+      id,
+      metadata: response.data.metadata,
+      config: {
+        vaultUrl,
+        authStrategy
+      },
+      name: response.data.metadata?.originalFileName
+    };
+    if (download) {
+      await wrappedFetch(response.data.url, { method: "GET" }).then((response2) => response2.blob()).then((blob) => fileParams.content = blob);
+    }
+    return new VaultFile(fileParams);
+  }
+  /**
+   * Creates a new VaultFile instance from given content.
+   *
+   * @param params - The parameters for creating a VaultFile from content
+   * @param params.name - The name of the file
+   * @param params.content - The content of the file
+   * @param params.config - The configuration for the VaultFile
+   * @param params.upload - Whether to upload the file (default: false)
+   * @returns A new VaultFile instance
+   *
+   * @example
+   * ```ts
+   * // Lazily upload the file content
+   * const file = new File(['content'], 'document.txt')
+   * const vaultFile = await VaultFile.fromContent({
+   *     name: 'document.txt',
+   *     content: file,
+   *     config: {
+   *         vaultUrl,
+   *         authStrategy,
+   *     }
+   * })
+   * await vaultFile.upload()
+   * ```
    *
    * @example
+   * ```ts
+   * // Upload the file content while creating the instance
    * const file = new File(['content'], 'document.txt')
-   * await vaultFile.addHashToName(file)
-   * // vaultFile.name becomes: "a1b2c3...xyz-document.txt"
+   * const vaultFile = await VaultFile.fromContent({
+   *     name: 'document.txt',
+   *     content: file,
+   *     config: {
+   *         vaultUrl,
+   *         authStrategy,
+   *     },
+   *     upload: true
+   * })
+   * ```
+   */
+  static async fromContent(params) {
+    const { name, content, config, upload = false } = params;
+    const { vaultUrl, authStrategy } = config;
+    const sha256sum = await getFileHash(content);
+    const file = new VaultFile({
+      content,
+      config: {
+        vaultUrl,
+        authStrategy
+      },
+      id: sha256sum,
+      name
+    });
+    const createdFile = await file._createFile();
+    if (upload) {
+      await file.upload(file.content, createdFile.uploadUrl);
+    }
+    return file;
+  }
+  /**
+   * Populates the metadata of the file instance.
    *
-   * @param file - The file to generate a hash for
-   * @returns The new filename with the hash prefix
+   * @returns The file instance
+   * @throws {Error} If the file ID is not set
+   * @throws {FetchError} If the metadata fetch fails
    */
-  async addHashToName(file) {
-    const fileHash = await getFileHash(file);
-    if (!this.name.includes(fileHash))
-      this.name = `${fileHash}-${this.name}`;
-    return this.name;
+  async populateMetadata() {
+    try {
+      this.metadata = await this.getFileMetadata();
+      this.name = this.metadata.originalFileName;
+      this.id = this.metadata.id;
+      return this;
+    } catch (error) {
+      console.error("Error fetching file metadata", error);
+    }
   }
   /**
-   * Uploads a file to the vault.
+   * Gets the vault reference for this file.
+   *
+   * @returns The vault reference in the format `vault://{fileId}`
+   * @throws {Error} If the file ID is not set
+   */
+  getVaultReference() {
+    if (!this.id) {
+      throw new Error("File ID is not set");
+    }
+    return `vault://${this.id}`;
+  }
+  /**
+   * Fetches the metadata of the file.
+   *
+   * @returns The metadata of the file
+   * @throws {Error} If the file ID is not set
+   * @throws {FetchError} If the metadata fetch fails
+   */
+  async getFileMetadata() {
+    if (!this.id) {
+      throw new Error("File ID is not set");
+    }
+    const response = await this._fetch({
+      method: "GET",
+      path: `/v2/files/${this.id}/metadata`
+    });
+    return response;
+  }
+  /**
+   * Fetches a upload URL for the file.
+   *
+   * @returns The upload URL for the file
+   * @throws {Error} If the vault service returns an invalid response
+   * @throws {FetchError} If the upload URL fetch fails
+   */
+  async getUploadUrl() {
+    if (this.lastUploadUrl && this.lastUploadUrl.expiresAt > /* @__PURE__ */ new Date()) {
+      return this.lastUploadUrl.url;
+    }
+    if (!this.id) {
+      const createdFile = await this._createFile();
+      this.id = createdFile.id;
+      this.metadata = createdFile.metadata;
+      this.name = createdFile.metadata?.originalFileName;
+      this.lastUploadUrl = { url: new URL(createdFile.uploadUrl), expiresAt: new Date(createdFile.expiresAt) };
+      return this.lastUploadUrl.url;
+    }
+    const response = await this._fetch({
+      method: "PUT",
+      path: `/v2/files/${this.id}`
+    }).then(GetUploadUrlResponseV2.safeParse);
+    if (!response.success) {
+      throw new Error(`Invalid response from vault service. ${JSON.stringify(response.error)}`);
+    }
+    this.lastUploadUrl = { url: new URL(response.data.uploadUrl), expiresAt: new Date(response.data.expiresAt) };
+    return this.lastUploadUrl.url;
+  }
+  /**
+   * Fetches a download URL for the file.
    *
-   * Files are saved with the given file names, so files with the same name within the same workspace
-   * will overwrite each other. To prevent accidental overwrites and support multiple files with the
-   * same original name, you should call addHashToName() before uploading to add a unique content-based
-   * hash to the filename.
+   * @returns The download URL for the file
+   * @throws {Error} If the vault service returns an invalid response
+   * @throws {Error} If not file ID, name or content is set
+   * @throws {FetchError} If the download URL fetch fails
+   */
+  async getDownloadUrl() {
+    if (this.lastDownloadUrl && this.lastDownloadUrl.expiresAt > /* @__PURE__ */ new Date()) {
+      return this.lastDownloadUrl.url;
+    }
+    if (!this.id && !this.name && !this.content) {
+      throw new Error("File was not created yet");
+    }
+    const id = this.id ?? this.metadata?.id ?? (this.content ? await getFileHash(this.content) : this.name);
+    const response = await this._fetch({
+      method: "GET",
+      path: `/v2/files/${id}`
+    });
+    this.lastDownloadUrl = { url: new URL(response.url), expiresAt: new Date(response.expiresAt) };
+    return this.lastDownloadUrl.url;
+  }
+  /**
+   * Uploads a file to the vault.
    *
    * @example
+   * ```ts
    * const file = new File(['content'], 'document.txt')
-   * await vaultFile.addHashToName(file) // Adds hash prefix to filename
+   * const vaultFile = await VaultFile.fromBlob('document.txt', file, { vaultUrl, authStrategy })
    * await vaultFile.upload(file)
+   * ```
    *
-   * @param file - The file to upload to the vault
+   * @param file - The file to upload to the vault. If not provided, the file content will be taken from the `content` property.
    * @throws {FetchError} If the upload fails
+   * @throws {Error} If the file content is not set and no file is provided
    * @returns Promise that resolves when upload is complete
    */
-  async upload(file) {
-    const uploadUrl = await this.getUploadUrl();
-    const response = await fetch(uploadUrl, {
+  async upload(file, url) {
+    if (!file && !this.content) {
+      throw new Error("Missing file content. Use fromBlob() to create a file with content, or provide a file to upload.");
+    }
+    const uploadUrl = url ?? await this.getUploadUrl();
+    await wrappedFetch(uploadUrl, {
       method: "PUT",
-      body: file
+      body: file ?? this.content
     });
-    if (!response.ok) {
-      throw new FetchError(`Error uploading file ${this.name}: ${response.status} ${response.statusText}`, response);
-    }
   }
   async download(responseType = "blob") {
     const downloadUrl = await this.getDownloadUrl();
-    const response = await fetch(downloadUrl, {
+    const response = await wrappedFetch(downloadUrl, {
       method: "GET"
     });
-    if (!response.ok) {
-      throw new FetchError(`Error downloading file ${this.name}: ${response.status} ${response.statusText}`, response);
-    }
     const blob = await response.blob();
     if (responseType === "blob")
       return blob;
@@ -172,15 +417,21 @@ class APIKeyAuthStrategy {
   }
 }
 
-function useVault(vaultUrl, authStrategy) {
-  function createVaultFile(name) {
-    return new VaultFile({
+function vaultClient(config) {
+  function createFromContent(name, content) {
+    return VaultFile.fromContent({
       name,
-      authStrategy,
-      vaultUrl
+      content,
+      config
+    });
+  }
+  function createFromReference(reference) {
+    return VaultFile.fromVaultReference({
+      reference,
+      config
     });
   }
-  return { createVaultFile };
+  return { createFromContent, createFromReference };
 }
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, useVault };
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, vaultClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/vault-sdk",
-  "version": "0.0.12",
+  "version": "1.0.0",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -9,7 +9,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs"
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
     }
   },
   "main": "dist/index.mjs",
@@ -17,26 +18,28 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "test": "vitest",
+    "build": "unbuild",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "check": "bun run lint && bun tsc --noEmit"
+  },
   "dependencies": {
-    "ofetch": "1.4.1"
+    "@meistrari/vault-shared": "workspace:*",
+    "ofetch": "1.4.1",
+    "zod": "3.23.8"
   },
   "devDependencies": {
-    "vitest": "2.1.9",
     "@types/bun": "latest",
     "msw": "2.6.8",
-    "unbuild": "2.0.0"
+    "unbuild": "2.0.0",
+    "vitest": "2.1.9"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "test": "vitest",
-    "build": "unbuild",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "check": "bun run lint && bun tsc --noEmit"
   }
-}
+}