@meistrari/vault-sdk-sdk

This is the SDK for Vault V2.

Installation

ni @meistrari/vault-sdk

Table of Contents

• Core Concepts
• Quick Start
• Authentication Strategies
• API Reference
  • VaultFile
  • Vault Client
  • Permalinks
• Advanced Usage

Core Concepts

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

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({
    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

Authentication Strategies

The SDK provides two authentication strategies:

DataTokenAuthStrategy

Used for internal calls to the vault service. Passes the data token as the x-data-token header.

import { DataTokenAuthStrategy } from '@meistrari/vault-sdk'

const authStrategy = new DataTokenAuthStrategy('[your-data-token]')

APIKeyAuthStrategy

Used for external calls through the API Gateway. Passes the API key as the Authorization header.

[!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

import { APIKeyAuthStrategy } from '@meistrari/vault-sdk'

const authStrategy = new APIKeyAuthStrategy('[your-api-key]')

API Reference

VaultFile

The main class for interacting with vault files.

Static Methods

VaultFile.fromContent(params, options?)

Creates a new VaultFile from content (File or Blob).

const vaultFile = await VaultFile.fromContent({
    name: 'document.txt',
    content: new File(['content'], 'document.txt'),
    config: {
        vaultUrl,
        authStrategy
    },
    upload: false // Set to true to upload immediately
}, { signal: abortSignal }) // Optional abort signal

VaultFile.fromVaultReference(params, options?)

Creates a VaultFile instance from an existing vault reference.

const vaultFile = await VaultFile.fromVaultReference({
    reference: 'vault://abc123...',
    config: {
        vaultUrl,
        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.

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.

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.

const stream = file.stream()
await vaultFile.uploadStream(stream, {
    contentLength: file.size,
    contentType: 'video/mp4'
})

download(responseType?, options?)

Downloads the file content from the vault.

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.

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.

const reference = vaultFile.getVaultReference() // 'vault://abc123...'

getFileMetadata(options?)

Fetches the file's metadata from the vault.

const metadata = await vaultFile.getFileMetadata()
// Returns FileMetadata with properties like originalFileName, mimeType, size, etc.

populateMetadata(options?)

Populates the file instance's metadata by fetching it from the vault.

await vaultFile.populateMetadata()
console.log(vaultFile.metadata)

getUploadUrl(options?)

Gets a pre-signed upload URL for the file.

const uploadUrl = await vaultFile.getUploadUrl({ expiresIn: 3600 }) // 1 hour

getDownloadUrl(options?)

Gets a pre-signed download URL for the file.

const downloadUrl = await vaultFile.getDownloadUrl({ expiresIn: 3600 }) // 1 hour

delete(options?)

Deletes the file from the vault.

await vaultFile.delete()

createPermalink(params?, options?)

Creates a permalink for the file. Requires workspace ID to be set in metadata.

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.

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.

import { vaultClient, DataTokenAuthStrategy } from '@meistrari/vault-sdk'

const client = vaultClient({
    vaultUrl: 'https://vault.tela.com',
    authStrategy: new DataTokenAuthStrategy('[your-data-token]')
})

// Create from content
const vaultFile = await client.createFromContent(
    'document.txt',
    new File(['content'], 'document.txt')
)

// 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' }
)

Permalinks

Permalinks are public, optionally time-limited URLs for files.

Permalink.create(config, params, options?)

Creates a new permalink.

import { Permalink } from '@meistrari/vault-sdk'

const permalink = await Permalink.create(config, {
    fileId: 'abc123...',
    workspaceId: 'workspace-id',
    expiresIn: 86400 // 24 hours (optional)
})

console.log(permalink.url)

Permalink.fromId(config, id)

Retrieves a permalink by its ID.

const permalink = await Permalink.fromId(config, 'permalink-id')

permalink.delete(options?)

Deletes the permalink.

await permalink.delete()

Advanced Usage

Complete Workflow Example

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

// 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:

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:

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

const vaultFile = await VaultFile.fromVaultReference({
    reference: 'vault://abc123...',
    config
})

// Load metadata
await vaultFile.populateMetadata()

console.log(vaultFile.metadata.originalFileName)
console.log(vaultFile.metadata.mimeType)
console.log(vaultFile.metadata.size)
console.log(vaultFile.metadata.workspaceId)