@meistrari/vault-sdk 0.0.13 → 1.0.0

package/README.md

@@ -11,28 +11,91 @@ ni @meistrari/vault-sdk-sdk
 ## Usage
 
 The main component of the SDK is the `VaultFile` class.
-It accepts the vault url and an auth strategy, and provides methods to upload and download that file.
+It provides methods to upload, download, and reference files in the vault.
+
+### Creating Files
+
+To create a new file in the vault, use `VaultFile.fromContent`:
 
 ```ts
-import { VaultFile } from '@meistrari/vault-sdk'
+const vaultFile = await VaultFile.fromContent({
+    name: 'document.txt', // Original filename
+    content: new File(['content'], 'document.txt'), // File content
+    config: {
+        vaultUrl,
+        authStrategy: new DataTokenAuthStrategy(dataToken)
+    },
+    upload: true // Optional: upload immediately
+})
+```
 
-const dataToken = '[some-data-token]'
-const vaultUrl = Bun.env.VAULT_URL ?? 'https://vault.tela.com'
+### Retrieving Files
+
+To retrieve a file using a vault reference, use `VaultFile.fromVaultReference`:
+
+```ts
+const vaultFile = await VaultFile.fromVaultReference({
+    reference: 'vault://1234567890', // The vault reference
+    config: {
+        vaultUrl,
+        authStrategy: new DataTokenAuthStrategy(dataToken)
+    },
+    download: false // Optional: download immediately if true
+})
+```
+
+## Basic Usage Flow
+
+The typical workflow with the SDK involves:
+
+1. Creating a file in the vault using `VaultFile.fromContent`
+2. Getting a reference to that file with `getVaultReference()`
+3. Later, retrieving the file using `VaultFile.fromVaultReference`
 
-const vaultFile = new VaultFile('file.txt', vaultUrl, new DataTokenAuthStrategy(dataToken))
-const localFile = Bun.file('path/to/local/file.txt')
+Here's an example showing the complete flow:
 
-await vaultFile.upload(localFile)
+```ts
+import { VaultFile, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
 
-const downloadedFile = await vaultFile.download()
+const dataToken = '[some-data-token]'
+const vaultUrl = Bun.env.VAULT_URL ?? 'https://vault.tela.com'
 
-console.log(downloadedFile)
+// Step 1: Create and upload a new file
+const fileContent = Bun.file('path/to/local/file.txt')
+const vaultFile = await VaultFile.fromContent({
+    name: 'file.txt',
+    content: fileContent,
+    config: {
+        vaultUrl,
+        authStrategy: new DataTokenAuthStrategy(dataToken)
+    },
+    upload: true // Upload immediately
+})
+
+// Step 2: Get a reference to store in your database or application
+const vaultReference = vaultFile.getVaultReference() // e.g. 'vault://1234567890'
+console.log(`Store this reference: ${vaultReference}`)
+
+// ... Later, in another part of your application ...
+
+// Step 3: Retrieve the file using the reference
+const retrievedFile = await VaultFile.fromVaultReference({
+    reference: vaultReference,
+    config: {
+        vaultUrl,
+        authStrategy: new DataTokenAuthStrategy(dataToken)
+    },
+    download: false // Set to true to download immediately
+})
+
+// Step 4: Download the content when needed
+const fileContent = await retrievedFile.download()
+console.log(fileContent)
 ```
 
-### The `useVault` function
+### Using the useVault helper
 
-In order to simplify the creation of multiple `VaultFile` instances, the `useVault` function is exported.
-It takes the vault url and an auth strategy, and returns a function that creates a `VaultFile` instance using those parameters.
+The SDK provides a convenient `useVault` helper function that simplifies creating vault files:
 
 ```ts
 import { useVault, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
@@ -40,17 +103,28 @@ import { useVault, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
 const dataToken = '[some-data-token]'
 const vaultUrl = Bun.env.VAULT_URL ?? 'https://vault.tela.com'
 
-const { createVaultFile } = useVault(vaultUrl, new DataTokenAuthStrategy(dataToken))
-const vaultFile = createVaultFile('test.txt')
+// Create a vault instance
+const vault = useVault({
+    vaultUrl,
+    authStrategy: new DataTokenAuthStrategy(dataToken)
+})
 
-const localFile = Bun.file('./package.json')
+// Create a file from content
+const fileFromContent = vault.createFromContent(
+    'document.txt',
+    new File(['content'], 'document.txt')
+)
 
-await vaultFile.upload(localFile)
+// Create a file from a vault reference
+const fileFromReference = vault.createFromReference('vault://1234567890')
+```
 
-const downloadedFile = await vaultFile.download()
+The `useVault` helper provides two methods:
 
-console.log(downloadedFile)
-```
+- `createFromContent(name, content)`: Creates a new `VaultFile` instance from a name and content (Blob or File)
+- `createFromReference(reference)`: Creates a new `VaultFile` instance from a vault reference string
+
+This helper makes it more convenient to work with multiple vault files using the same configuration.
 
 ### Auth strategies
 
@@ -72,9 +146,16 @@ const authStrategy = new DataTokenAuthStrategy(dataToken)
 #### APIKeyAuthStrategy
 
 It takes an API key, and passes it as the `Authorization` header in requests to the vault.
-Use this when performing external calls to the vault, such as from the frontend.
+Use this when performing external calls **through the API Gateway**, such as from the frontend.
 Since the clerk token is also passed as the `Authorization` header, this strategy can also be used with the value of the `__session` cookie instead of an API key.
-For vault, there's no real difference between using an API key and the clerk token, since it only needs the workspace ID, and that's provided by both types of credentials.
+
+> [!WARNING]
+> The vault service itself does not support API Keys, it only understands data tokens.
+> To use this strategy, the request **must** go through the API Gateway.
+> For that, the gateway URL should be used instead of the vault service URL.
+>
+> Use this: `https://staging.api.tela.com/_services/vault`.<br>
+> Instead of this: `https://vault.tela.com`
 
 ```ts
 import { APIKeyAuthStrategy } from '@meistrari/vault-sdk'
@@ -83,23 +164,3 @@ const apiKey = '[some-api-key]'
 
 const authStrategy = new APIKeyAuthStrategy(apiKey)
 ```
-
-### Retrieving files with a vault ref
-
-Both the `VaultFile` class and the `createVaultFile` function accept a vault ref as the name of the file.
-The vault ref is a string with the form `vault://file-name.ext`.
-The workspace ID is obtained from the authentication data, and doesn't need to be explicitly passed.
-
-```ts
-import { useVault, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
-
-const dataToken = '[some-data-token]'
-const vaultUrl = Bun.env.VAULT_URL ?? 'https://vault.tela.com'
-
-const { createVaultFile } = useVault(vaultUrl, new DataTokenAuthStrategy(dataToken))
-const vaultFile = createVaultFile('vault://file-name.ext')
-
-const downloadedFile = await vaultFile.download()
-
-console.log(downloadedFile)
-```

package/dist/index.cjs

@@ -1,11 +1,22 @@
 'use strict';
 
+const schemas = require('@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) {
@@ -30,114 +41,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) => schemas.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) => schemas.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(schemas.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;
@@ -174,19 +419,25 @@ 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 };
 }
 
 exports.APIKeyAuthStrategy = APIKeyAuthStrategy;
 exports.DataTokenAuthStrategy = DataTokenAuthStrategy;
 exports.FetchError = FetchError;
 exports.VaultFile = VaultFile;
-exports.useVault = useVault;
+exports.vaultClient = vaultClient;