@meistrari/vault-sdk 1.6.2 → 1.7.0

package/README.md

@@ -8,159 +8,456 @@ This is the SDK for Vault V2.
 ni @meistrari/vault-sdk-sdk
 ```
 
-## Usage
+## Table of Contents
 
-The main component of the SDK is the `VaultFile` class.
-It provides methods to upload, download, and reference files in the vault.
+- [Core Concepts](#core-concepts)
+- [Quick Start](#quick-start)
+- [Authentication Strategies](#authentication-strategies)
+- [API Reference](#api-reference)
+  - [VaultFile](#vaultfile)
+  - [Vault Client](#vault-client)
+  - [Permalinks](#permalinks)
+- [Advanced Usage](#advanced-usage)
 
-### Creating Files
+## Core Concepts
 
-To create a new file in the vault, use `VaultFile.fromContent`:
+The SDK revolves around two main components:
+
+1. **VaultFile** - The primary class for interacting with files in the vault
+2. **Vault Client** - A helper function (`vaultClient`) that simplifies creating VaultFile instances with shared configuration
+
+Files in the vault are identified by vault references in the format `vault://{fileId}`.
+
+## Quick Start
 
 ```ts
+import { VaultFile, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
+
+const config = {
+    vaultUrl: 'https://vault.tela.com',
+    authStrategy: new DataTokenAuthStrategy('[your-data-token]')
+}
+
+// Upload a new file
+const file = new File(['Hello World'], 'hello.txt')
 const vaultFile = await VaultFile.fromContent({
-    content: new File(['content'], 'document.txt'), // File content
-    name: 'document.txt', // Optional: original filename
-    config: {
-        vaultUrl,
-        authStrategy: new DataTokenAuthStrategy(dataToken)
-    },
-    upload: true // Optional: upload immediately
+    name: 'hello.txt',
+    content: file,
+    config,
+    upload: true
 })
+
+// Get the vault reference to store in your database
+const reference = vaultFile.getVaultReference() // 'vault://abc123...'
+
+// Later, retrieve and download the file
+const retrieved = await VaultFile.fromVaultReference({
+    reference,
+    config
+})
+const content = await retrieved.download() // Returns a Blob
 ```
 
-### Retrieving Files
+## Authentication Strategies
+
+The SDK provides two authentication strategies:
 
-To retrieve a file using a vault reference, use `VaultFile.fromVaultReference`:
+### DataTokenAuthStrategy
+
+Used for internal calls to the vault service. Passes the data token as the `x-data-token` header.
 
 ```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
-})
-```
+import { DataTokenAuthStrategy } from '@meistrari/vault-sdk'
 
-## Basic Usage Flow
+const authStrategy = new DataTokenAuthStrategy('[your-data-token]')
+```
 
-The typical workflow with the SDK involves:
+### APIKeyAuthStrategy
 
-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`
+Used for external calls **through the API Gateway**. Passes the API key as the `Authorization` header.
 
-Here's an example showing the complete flow:
+> [!WARNING]
+> The vault service itself does not support API Keys directly. When using this strategy, requests **must** go through the API Gateway.
+>
+> ✅ Use: `https://staging.api.tela.com/_services/vault`
+> ❌ Not: `https://staging.vault.tela.com`
 
 ```ts
-import { VaultFile, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
+import { APIKeyAuthStrategy } from '@meistrari/vault-sdk'
+
+const authStrategy = new APIKeyAuthStrategy('[your-api-key]')
+```
 
-const dataToken = '[some-data-token]'
-const vaultUrl = Bun.env.VAULT_URL ?? 'https://vault.tela.com'
+## API Reference
 
-// Step 1: Create and upload a new file
-const fileContent = Bun.file('path/to/local/file.txt')
+### VaultFile
+
+The main class for interacting with vault files.
+
+#### Static Methods
+
+##### `VaultFile.fromContent(params, options?)`
+
+Creates a new VaultFile from content (File or Blob).
+
+```ts
 const vaultFile = await VaultFile.fromContent({
-    content: fileContent,
-    name: 'file.txt', // Optional: original filename
+    name: 'document.txt',
+    content: new File(['content'], 'document.txt'),
     config: {
         vaultUrl,
-        authStrategy: new DataTokenAuthStrategy(dataToken)
+        authStrategy
     },
-    upload: true // Upload immediately
-})
+    upload: false // Set to true to upload immediately
+}, { signal: abortSignal }) // Optional abort signal
+```
 
-// 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}`)
+##### `VaultFile.fromVaultReference(params, options?)`
 
-// ... Later, in another part of your application ...
+Creates a VaultFile instance from an existing vault reference.
 
-// Step 3: Retrieve the file using the reference
-const retrievedFile = await VaultFile.fromVaultReference({
-    reference: vaultReference,
+```ts
+const vaultFile = await VaultFile.fromVaultReference({
+    reference: 'vault://abc123...',
     config: {
         vaultUrl,
-        authStrategy: new DataTokenAuthStrategy(dataToken)
+        authStrategy
     },
     download: false // Set to true to download immediately
+}, { signal: abortSignal }) // Optional abort signal
+```
+
+##### `VaultFile.fromStream(params, options?)`
+
+Creates a VaultFile for streaming upload workflows. Useful for large files to avoid loading the entire file into memory.
+
+```ts
+const vaultFile = await VaultFile.fromStream({
+    name: 'large-video.mp4',
+    contentLength: 100 * 1024 * 1024, // 100MB
+    contentType: 'video/mp4',
+    config: { vaultUrl, authStrategy }
+}, { signal: abortSignal })
+
+// Upload using a stream
+const stream = file.stream()
+await vaultFile.uploadStream(stream, {
+    contentLength: file.size,
+    contentType: file.type
 })
+```
+
+#### Instance Methods
+
+##### `upload(file?, url?, options?)`
+
+Uploads the file to the vault. If no file is provided, uses the content from the VaultFile instance.
+
+```ts
+await vaultFile.upload() // Uses vaultFile.content
+// or
+await vaultFile.upload(someBlob) // Upload specific blob
+```
+
+##### `uploadStream(stream, options)`
+
+Uploads a file using a ReadableStream for memory-efficient processing of large files.
+
+```ts
+const stream = file.stream()
+await vaultFile.uploadStream(stream, {
+    contentLength: file.size,
+    contentType: 'video/mp4'
+})
+```
+
+##### `download(responseType?, options?)`
+
+Downloads the file content from the vault.
+
+```ts
+const blob = await vaultFile.download() // Returns Blob
+const base64 = await vaultFile.download('base64') // Returns base64 string
+```
+
+##### `downloadStream(options?)`
+
+Downloads the file as a ReadableStream for memory-efficient processing.
+
+```ts
+const stream = await vaultFile.downloadStream()
+const reader = stream.getReader()
+
+while (true) {
+    const { done, value } = await reader.read()
+    if (done)
+        break
+    console.log('Chunk size:', value.length)
+}
+```
+
+##### `getVaultReference()`
+
+Returns the vault reference string for this file.
+
+```ts
+const reference = vaultFile.getVaultReference() // 'vault://abc123...'
+```
+
+##### `getFileMetadata(options?)`
+
+Fetches the file's metadata from the vault.
+
+```ts
+const metadata = await vaultFile.getFileMetadata()
+// Returns FileMetadata with properties like originalFileName, mimeType, size, etc.
+```
+
+##### `populateMetadata(options?)`
 
-// Step 4: Download the content when needed
-const fileContent = await retrievedFile.download()
-console.log(fileContent)
+Populates the file instance's metadata by fetching it from the vault.
+
+```ts
+await vaultFile.populateMetadata()
+console.log(vaultFile.metadata)
 ```
 
-### Using the useVault helper
+##### `getUploadUrl(options?)`
 
-The SDK provides a convenient `useVault` helper function that simplifies creating vault files:
+Gets a pre-signed upload URL for the file.
 
 ```ts
-import { useVault, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
+const uploadUrl = await vaultFile.getUploadUrl({ expiresIn: 3600 }) // 1 hour
+```
+
+##### `getDownloadUrl(options?)`
+
+Gets a pre-signed download URL for the file.
 
-const dataToken = '[some-data-token]'
-const vaultUrl = Bun.env.VAULT_URL ?? 'https://vault.tela.com'
+```ts
+const downloadUrl = await vaultFile.getDownloadUrl({ expiresIn: 3600 }) // 1 hour
+```
 
-// Create a vault instance
-const vault = useVault({
-    vaultUrl,
-    authStrategy: new DataTokenAuthStrategy(dataToken)
+##### `delete(options?)`
+
+Deletes the file from the vault.
+
+```ts
+await vaultFile.delete()
+```
+
+##### `createPermalink(params?, options?)`
+
+Creates a permalink for the file. Requires workspace ID to be set in metadata.
+
+```ts
+await vaultFile.populateMetadata() // Ensure metadata is loaded
+const permalink = await vaultFile.createPermalink({ expiresIn: 86400 }) // 24 hours
+console.log(permalink.url) // Public URL
+```
+
+##### `getPermalinks(options?)`
+
+Gets all valid permalinks for the file.
+
+```ts
+const permalinks = await vaultFile.getPermalinks()
+for (const permalink of permalinks) {
+    console.log(permalink.url, permalink.expiresAt)
+}
+```
+
+### Vault Client
+
+The `vaultClient` helper simplifies working with multiple files using shared configuration.
+
+```ts
+import { vaultClient, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
+
+const client = vaultClient({
+    vaultUrl: 'https://vault.tela.com',
+    authStrategy: new DataTokenAuthStrategy('[your-data-token]')
 })
 
-// Create a file from content
-const fileFromContent = vault.createFromContent(
+// Create from content
+const vaultFile = await client.createFromContent(
     'document.txt',
     new File(['content'], 'document.txt')
 )
 
-// Create a file from a vault reference
-const fileFromReference = vault.createFromReference('vault://1234567890')
+// Create from reference
+const retrieved = await client.createFromReference('vault://abc123...')
+
+// Create from stream
+const streamFile = await client.createFromStream(
+    'video.mp4',
+    100 * 1024 * 1024, // 100MB
+    { contentType: 'video/mp4' }
+)
 ```
 
-The `useVault` helper provides two methods:
+### Permalinks
 
-- `createFromContent(content, name?)`: Creates a new `VaultFile` instance from content (Blob or File) and an optional name
-- `createFromReference(reference)`: Creates a new `VaultFile` instance from a vault reference string
+Permalinks are public, optionally time-limited URLs for files.
 
-This helper makes it more convenient to work with multiple vault files using the same configuration.
+#### `Permalink.create(config, params, options?)`
 
-### Auth strategies
+Creates a new permalink.
 
-The SDK provides two auth strategies: `DataTokenAuthStrategy` and `APIKeyAuthStrategy`.
+```ts
+import { Permalink } from '@meistrari/vault-sdk'
 
-#### DataTokenAuthStrategy
+const permalink = await Permalink.create(config, {
+    fileId: 'abc123...',
+    workspaceId: 'workspace-id',
+    expiresIn: 86400 // 24 hours (optional)
+})
 
-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`.
+console.log(permalink.url)
+```
+
+#### `Permalink.fromId(config, id)`
+
+Retrieves a permalink by its ID.
 
 ```ts
-import { DataTokenAuthStrategy } from '@meistrari/vault-sdk'
+const permalink = await Permalink.fromId(config, 'permalink-id')
+```
+
+#### `permalink.delete(options?)`
 
-const dataToken = '[some-data-token]'
+Deletes the permalink.
 
-const authStrategy = new DataTokenAuthStrategy(dataToken)
+```ts
+await permalink.delete()
 ```
 
-#### APIKeyAuthStrategy
+## Advanced Usage
 
-It takes an API key, and passes it as the `Authorization` header in requests to the vault.
-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.
+### Complete Workflow Example
 
-> [!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 { VaultFile, DataTokenAuthStrategy } from '@meistrari/vault-sdk'
+
+const config = {
+    vaultUrl: 'https://vault.tela.com',
+    authStrategy: new DataTokenAuthStrategy('[your-data-token]')
+}
+
+// 1. Create and upload a file
+const file = new File(['content'], 'document.txt')
+const vaultFile = await VaultFile.fromContent({
+    name: 'document.txt',
+    content: file,
+    config,
+    upload: true
+})
+
+// 2. Store the reference in your database
+const reference = vaultFile.getVaultReference()
+await db.saveDocument({ vaultReference: reference })
+
+// 3. Later, retrieve the file
+const doc = await db.getDocument()
+const retrieved = await VaultFile.fromVaultReference({
+    reference: doc.vaultReference,
+    config,
+    download: true
+})
+
+// 4. Use the content
+const blob = retrieved.content // Already downloaded
+console.log('File size:', blob.size)
+```
+
+### Streaming Large Files
 
 ```ts
-import { APIKeyAuthStrategy } from '@meistrari/vault-sdk'
+// Upload a large file efficiently
+const vaultFile = await VaultFile.fromStream({
+    name: 'large-file.bin',
+    contentLength: largeFile.size,
+    contentType: largeFile.type,
+    config
+})
+
+await vaultFile.uploadStream(largeFile.stream(), {
+    contentLength: largeFile.size,
+    contentType: largeFile.type
+})
+
+// Download a large file efficiently
+const stream = await vaultFile.downloadStream()
+// Process stream in chunks without loading entire file
+```
+
+### Abort Requests
+
+All methods that make network requests support AbortSignal for request cancellation:
+
+```ts
+const controller = new AbortController()
+
+// Cancel after 5 seconds
+setTimeout(() => controller.abort(), 5000)
+
+try {
+    const vaultFile = await VaultFile.fromContent({
+        name: 'document.txt',
+        content: file,
+        config
+    }, { signal: controller.signal })
+
+    // Upload with abort signal
+    await vaultFile.upload(undefined, undefined, { signal: controller.signal })
+
+    console.log('Upload successful')
+}
+catch (error) {
+    if (error.name === 'AbortError') {
+        console.log('Upload was cancelled')
+    }
+    else {
+        throw error
+    }
+}
+```
+
+You can also cancel downloads and other operations:
+
+```ts
+const controller = new AbortController()
+
+// Start download
+const downloadPromise = vaultFile.download('blob', { signal: controller.signal })
+
+// Cancel if user clicks a button
+cancelButton.addEventListener('click', () => controller.abort())
+
+try {
+    const blob = await downloadPromise
+    console.log('Download complete:', blob.size)
+}
+catch (error) {
+    if (error.name === 'AbortError') {
+        console.log('Download cancelled by user')
+    }
+}
+```
+
+### Working with Metadata
+
+```ts
+const vaultFile = await VaultFile.fromVaultReference({
+    reference: 'vault://abc123...',
+    config
+})
 
-const apiKey = '[some-api-key]'
+// Load metadata
+await vaultFile.populateMetadata()
 
-const authStrategy = new APIKeyAuthStrategy(apiKey)
+console.log(vaultFile.metadata.originalFileName)
+console.log(vaultFile.metadata.mimeType)
+console.log(vaultFile.metadata.size)
+console.log(vaultFile.metadata.workspaceId)
 ```

package/dist/index.cjs

@@ -221,7 +221,7 @@ async function detectFileMimeType(blob) {
 }
 
 const name = "@meistrari/vault-sdk";
-const version = "1.6.2";
+const version = "1.7.0";
 const license = "UNLICENSED";
 const repository = {
 	type: "git",
@@ -846,9 +846,29 @@ class VaultFile {
     const headers = new Headers();
     headers.set("Content-Type", mimeType);
     headers.set("Content-Length", contentLength.toString());
+    let content = stream;
+    if (stream instanceof ReadableStream && typeof Bun !== "undefined") {
+      console.warn(
+        "[Vault SDK - WARNING] Buffering file upload due to Bun fetch implementation. Large files may cause memory issues. Consider using Node.js for streaming uploads.",
+        { fileName: this.name, fileSize: contentLength }
+      );
+      const chunks = [];
+      const reader = stream.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done)
+            break;
+          chunks.push(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+      content = new Blob(chunks, { type: mimeType });
+    }
     await wrappedFetch(uploadUrl, {
       method: "PUT",
-      body: stream,
+      body: content,
       headers,
       signal
     });

package/dist/index.mjs

@@ -219,7 +219,7 @@ async function detectFileMimeType(blob) {
 }
 
 const name = "@meistrari/vault-sdk";
-const version = "1.6.2";
+const version = "1.7.0";
 const license = "UNLICENSED";
 const repository = {
 	type: "git",
@@ -844,9 +844,29 @@ class VaultFile {
     const headers = new Headers();
     headers.set("Content-Type", mimeType);
     headers.set("Content-Length", contentLength.toString());
+    let content = stream;
+    if (stream instanceof ReadableStream && typeof Bun !== "undefined") {
+      console.warn(
+        "[Vault SDK - WARNING] Buffering file upload due to Bun fetch implementation. Large files may cause memory issues. Consider using Node.js for streaming uploads.",
+        { fileName: this.name, fileSize: contentLength }
+      );
+      const chunks = [];
+      const reader = stream.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done)
+            break;
+          chunks.push(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+      content = new Blob(chunks, { type: mimeType });
+    }
     await wrappedFetch(uploadUrl, {
       method: "PUT",
-      body: stream,
+      body: content,
       headers,
       signal
     });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@meistrari/vault-sdk",
-    "version": "1.6.2",
+    "version": "1.7.0",
     "license": "UNLICENSED",
     "repository": {
         "type": "git",