@meistrari/vault-sdk 0.0.10 → 0.0.12

package/README.md

@@ -1,15 +1,105 @@
-# sdk
+# @meistrari/vault-sdk-sdk
 
-To install dependencies:
+This is the SDK for Vault V2.
+
+## Installation
 
 ```bash
-bun install
+ni @meistrari/vault-sdk-sdk
 ```
 
-To run:
+## Usage
 
-```bash
-bun run dist/index.ks
+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.
+
+```ts
+import { VaultFile } from '@meistrari/vault-sdk'
+
+const dataToken = '[some-data-token]'
+const vaultUrl = Bun.env.VAULT_URL ?? 'https://vault.tela.com'
+
+const vaultFile = new VaultFile('file.txt', vaultUrl, new DataTokenAuthStrategy(dataToken))
+const localFile = Bun.file('path/to/local/file.txt')
+
+await vaultFile.upload(localFile)
+
+const downloadedFile = await vaultFile.download()
+
+console.log(downloadedFile)
+```
+
+### The `useVault` function
+
+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.
+
+```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('test.txt')
+
+const localFile = Bun.file('./package.json')
+
+await vaultFile.upload(localFile)
+
+const downloadedFile = await vaultFile.download()
+
+console.log(downloadedFile)
 ```
 
-This project was created using `bun init` in bun v1.1.7. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+### Auth strategies
+
+The SDK provides two auth strategies: `DataTokenAuthStrategy` and `APIKeyAuthStrategy`.
+
+#### DataTokenAuthStrategy
+
+It takes a data token, and passes it as the `x-data-token` header in requests to the vault.
+Use this when performing internal calls to the vault, such as from `tela-api`.
+
+```ts
+import { DataTokenAuthStrategy } from '@meistrari/vault-sdk'
+
+const dataToken = '[some-data-token]'
+
+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.
+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.
+
+```ts
+import { APIKeyAuthStrategy } from '@meistrari/vault-sdk'
+
+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.d.mts

@@ -24,8 +24,8 @@ type VaultParams = {
     vaultUrl: string;
 };
 declare class VaultFile {
-    readonly name: string;
     readonly vaultUrl: string;
+    name: string;
     headers: Headers;
     constructor(params: VaultParams);
     getVaultUrl(): string;
@@ -34,6 +34,42 @@ declare class VaultFile {
     getDownloadUrl(): Promise<URL>;
     refreshAuth(authStrategy: AuthStrategy): void;
     _fetch(params: FetchParams): Promise<any>;
+    /**
+     * 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.
+     *
+     * The resulting filename format is: "{hash}-{originalName}"
+     *
+     * 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
+     * const file = new File(['content'], 'document.txt')
+     * await vaultFile.addHashToName(file)
+     * // vaultFile.name becomes: "a1b2c3...xyz-document.txt"
+     *
+     * @param file - The file to generate a hash for
+     * @returns The new filename with the hash prefix
+     */
+    addHashToName(file: Blob): Promise<string>;
+    /**
+     * Uploads a file to the vault.
+     *
+     * 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.
+     *
+     * @example
+     * const file = new File(['content'], 'document.txt')
+     * await vaultFile.addHashToName(file) // Adds hash prefix to filename
+     * await vaultFile.upload(file)
+     *
+     * @param file - The file to upload to the vault
+     * @throws {FetchError} If the upload fails
+     * @returns Promise that resolves when upload is complete
+     */
     upload(file: Blob): Promise<void>;
     download(responseType?: 'blob'): Promise<Blob>;
     download(responseType: 'base64'): Promise<string>;

package/dist/index.d.ts

@@ -24,8 +24,8 @@ type VaultParams = {
     vaultUrl: string;
 };
 declare class VaultFile {
-    readonly name: string;
     readonly vaultUrl: string;
+    name: string;
     headers: Headers;
     constructor(params: VaultParams);
     getVaultUrl(): string;
@@ -34,6 +34,42 @@ declare class VaultFile {
     getDownloadUrl(): Promise<URL>;
     refreshAuth(authStrategy: AuthStrategy): void;
     _fetch(params: FetchParams): Promise<any>;
+    /**
+     * 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.
+     *
+     * The resulting filename format is: "{hash}-{originalName}"
+     *
+     * 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
+     * const file = new File(['content'], 'document.txt')
+     * await vaultFile.addHashToName(file)
+     * // vaultFile.name becomes: "a1b2c3...xyz-document.txt"
+     *
+     * @param file - The file to generate a hash for
+     * @returns The new filename with the hash prefix
+     */
+    addHashToName(file: Blob): Promise<string>;
+    /**
+     * Uploads a file to the vault.
+     *
+     * 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.
+     *
+     * @example
+     * const file = new File(['content'], 'document.txt')
+     * await vaultFile.addHashToName(file) // Adds hash prefix to filename
+     * await vaultFile.upload(file)
+     *
+     * @param file - The file to upload to the vault
+     * @throws {FetchError} If the upload fails
+     * @returns Promise that resolves when upload is complete
+     */
     upload(file: Blob): Promise<void>;
     download(responseType?: 'blob'): Promise<Blob>;
     download(responseType: 'base64'): Promise<string>;

package/dist/index.mjs

@@ -14,6 +14,14 @@ async function blobToBase64(blob) {
   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) => {
@@ -22,8 +30,8 @@ var __publicField$1 = (obj, key, value) => {
 };
 class VaultFile {
   constructor(params) {
-    __publicField$1(this, "name");
     __publicField$1(this, "vaultUrl");
+    __publicField$1(this, "name");
     __publicField$1(this, "headers");
     this.name = params.name;
     this.vaultUrl = params.vaultUrl;
@@ -69,6 +77,47 @@ class VaultFile {
     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.
+   *
+   * The resulting filename format is: "{hash}-{originalName}"
+   *
+   * 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
+   * const file = new File(['content'], 'document.txt')
+   * await vaultFile.addHashToName(file)
+   * // vaultFile.name becomes: "a1b2c3...xyz-document.txt"
+   *
+   * @param file - The file to generate a hash for
+   * @returns The new filename with the hash prefix
+   */
+  async addHashToName(file) {
+    const fileHash = await getFileHash(file);
+    if (!this.name.includes(fileHash))
+      this.name = `${fileHash}-${this.name}`;
+    return this.name;
+  }
+  /**
+   * Uploads a file to the vault.
+   *
+   * 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.
+   *
+   * @example
+   * const file = new File(['content'], 'document.txt')
+   * await vaultFile.addHashToName(file) // Adds hash prefix to filename
+   * await vaultFile.upload(file)
+   *
+   * @param file - The file to upload to the vault
+   * @throws {FetchError} If the upload fails
+   * @returns Promise that resolves when upload is complete
+   */
   async upload(file) {
     const uploadUrl = await this.getUploadUrl();
     const response = await fetch(uploadUrl, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/vault-sdk",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -18,10 +18,10 @@
     "dist"
   ],
   "dependencies": {
-    "ofetch": "1.4.1",
-    "vitest": "2.1.8"
+    "ofetch": "1.4.1"
   },
   "devDependencies": {
+    "vitest": "2.1.9",
     "@types/bun": "latest",
     "msw": "2.6.8",
     "unbuild": "2.0.0"