@meistrari/vault-sdk 3.2.0 → 3.3.0

package/README.md

@@ -1,6 +1,8 @@
 # Vault SDK
 
-TypeScript SDK for interacting with the Vault file storage service. Provides file upload, download, streaming, hierarchy management, permalinks, and vault reference utilities.
+TypeScript SDK for interacting with the Vault file storage service. It supports file upload, download, streaming uploads, file hierarchies, public assets, permalinks, and vault reference utilities.
+
+Use the SDK when an application needs to store private files in Vault, publish stable public asset URLs such as avatars or logos, or keep durable `vault://` references instead of temporary presigned URLs.
 
 ## Installation
 
@@ -8,502 +10,30 @@ TypeScript SDK for interacting with the Vault file storage service. Provides fil
 bun add @meistrari/vault-sdk
 ```
 
-## Table of Contents
-
-- [Core Concepts](#core-concepts)
-- [Quick Start](#quick-start)
-- [Authentication Strategies](#authentication-strategies)
-- [API Reference](#api-reference)
-  - [VaultFile](#vaultfile)
-  - [Vault Client](#vault-client)
-  - [Permalinks](#permalinks)
-- [File Hierarchies](#file-hierarchies)
-- [Vault Reference Utilities](#vault-reference-utilities)
-- [Advanced Usage](#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
 
-```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({
-    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.
-
-```ts
-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`
-
-```ts
-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).
-
-```ts
-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.
-
-```ts
-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.
-
-```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?)`
-
-Populates the file instance's metadata by fetching it from the vault.
-
-```ts
-await vaultFile.populateMetadata()
-console.log(vaultFile.metadata)
-```
-
-##### `getUploadUrl(options?)`
-
-Gets a pre-signed upload URL for the file.
-
-```ts
-const uploadUrl = await vaultFile.getUploadUrl({ expiresIn: 3600 }) // 1 hour
-```
-
-##### `getDownloadUrl(options?)`
-
-Gets a pre-signed download URL for the file.
-
-```ts
-const downloadUrl = await vaultFile.getDownloadUrl({ expiresIn: 3600 }) // 1 hour
-```
-
-##### `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]')
+    authStrategy: new DataTokenAuthStrategy('[your-data-token]'),
 })
 
-// Create from content
 const vaultFile = await client.createFromContent(
-    'document.txt',
-    new File(['content'], 'document.txt')
+    new File(['Hello World'], 'hello.txt'),
+    { upload: true },
 )
 
-// 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' }
-)
+console.log(vaultFile.getVaultReference())
 ```
 
-### Permalinks
-
-Permalinks are public, optionally time-limited URLs for files.
-
-#### `Permalink.create(config, params, options?)`
-
-Creates a new permalink.
-
-```ts
-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.
-
-```ts
-const permalink = await Permalink.fromId(config, 'permalink-id')
-```
-
-#### `permalink.delete(options?)`
-
-Deletes the permalink.
-
-```ts
-await permalink.delete()
-```
-
-## File Hierarchies
-
-Files can be organized into parent-child relationships. See the [File Hierarchy Guide](docs/guides/file-hierarchy.md) for full details, patterns, and best practices.
-
-```ts
-// Create a child file
-const child = await parentFile.createChildFromContent({
-    name: 'page-1.png',
-    content: imageBlob,
-})
-
-// List children
-const children = await parentFile.getChildren()
-
-// Iterate children with auto-pagination
-for await (const child of parentFile.iterateChildren()) {
-    console.log(child.name)
-}
-```
+For a more detailed usage guide, see the [SDK guides](docs/guides/README.md).
 
-Options for handling edge cases:
+## Guides
 
-- `onMissingParent`: `'error'` (default) or `'create-as-root'`
-- `onParentConflict`: `'error'` (default), `'update-parent-id'`, or `'ignore'`
+- [SDK Guides](docs/guides/README.md)
 
-## Vault Reference Utilities
+## Main Exports
 
-Utilities for working with `vault://` URIs and S3 presigned URLs.
-
-```ts
-import {
-    isVaultReference,
-    extractVaultReferences,
-    isS3UrlExpired,
-    convertS3UrlToVaultReference,
-    extractVaultFileIdFromS3Url,
-} from '@meistrari/vault-sdk'
-
-isVaultReference('vault://abc-123') // true
-extractVaultReferences('See vault://a and vault://b') // ['vault://a', 'vault://b']
-isS3UrlExpired(presignedUrl) // boolean
-convertS3UrlToVaultReference(s3Url) // 'vault://...'
-```
-
-## Advanced Usage
-
-### Complete Workflow Example
-
-```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
-// 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
-})
-
-// 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)
-```
+The package exports `vaultClient`, `VaultFile`, `VaultAsset`, `Permalink`, `DataTokenAuthStrategy`, `APIKeyAuthStrategy`, and vault reference utility functions.