@meistrari/vault-sdk 0.0.12 → 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

@@ -0,0 +1,443 @@
+'use strict';
+
+const schemas = require('@meistrari/vault-shared/schemas');
+
+class FetchError extends Error {
+  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) {
+  const fileContent = new Uint8Array(await blob.arrayBuffer());
+  let content = "";
+  for (const part of fileContent)
+    content += String.fromCharCode(part);
+  return btoa(content);
+}
+
+async function getFileHash(blob) {
+  const arrayBuffer = await blob.arrayBuffer();
+  const hashBuffer = await crypto.subtle.digest("SHA-256", arrayBuffer);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hashHex;
+}
+
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+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 {
+  /**
+   * 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, "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;
+  }
+  /**
+   * 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 } = 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
+    });
+    const content = await response.json();
+    return content;
+  }
+  /**
+   * 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.
+   *
+   * @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
+   *
+   * @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')
+   * 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.
+   *
+   * @returns The file instance
+   * @throws {Error} If the file ID is not set
+   * @throws {FetchError} If the metadata fetch fails
+   */
+  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);
+    }
+  }
+  /**
+   * 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.
+   *
+   * @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')
+   * const vaultFile = await VaultFile.fromBlob('document.txt', file, { vaultUrl, authStrategy })
+   * await vaultFile.upload(file)
+   * ```
+   *
+   * @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, 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 ?? this.content
+    });
+  }
+  async download(responseType = "blob") {
+    const downloadUrl = await this.getDownloadUrl();
+    const response = await wrappedFetch(downloadUrl, {
+      method: "GET"
+    });
+    const blob = await response.blob();
+    if (responseType === "blob")
+      return blob;
+    return await blobToBase64(blob);
+  }
+}
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class DataTokenAuthStrategy {
+  constructor(dataToken) {
+    __publicField(this, "dataToken");
+    this.dataToken = dataToken;
+  }
+  getHeaders() {
+    return new Headers({
+      "x-data-token": this.dataToken
+    });
+  }
+}
+class APIKeyAuthStrategy {
+  constructor(apiKey) {
+    __publicField(this, "apiKey");
+    this.apiKey = apiKey;
+  }
+  getHeaders() {
+    return new Headers({
+      Authorization: this.apiKey
+    });
+  }
+}
+
+function vaultClient(config) {
+  function createFromContent(name, content) {
+    return VaultFile.fromContent({
+      name,
+      content,
+      config
+    });
+  }
+  function createFromReference(reference) {
+    return VaultFile.fromVaultReference({
+      reference,
+      config
+    });
+  }
+  return { createFromContent, createFromReference };
+}
+
+exports.APIKeyAuthStrategy = APIKeyAuthStrategy;
+exports.DataTokenAuthStrategy = DataTokenAuthStrategy;
+exports.FetchError = FetchError;
+exports.VaultFile = VaultFile;
+exports.vaultClient = vaultClient;