@meistrari/vault-sdk 3.1.1 → 3.2.1

package/README.md

@@ -1,11 +1,11 @@
-# @meistrari/vault-sdk-sdk
+# Vault SDK
 
-This is the SDK for Vault V2.
+TypeScript SDK for interacting with the Vault file storage service. Provides file upload, download, streaming, hierarchy management, permalinks, and vault reference utilities.
 
 ## Installation
 
 ```bash
-ni @meistrari/vault-sdk
+bun add @meistrari/vault-sdk
 ```
 
 ## Table of Contents
@@ -17,6 +17,8 @@ ni @meistrari/vault-sdk
   - [VaultFile](#vaultfile)
   - [Vault Client](#vault-client)
   - [Permalinks](#permalinks)
+- [File Hierarchies](#file-hierarchies)
+- [Vault Reference Utilities](#vault-reference-utilities)
 - [Advanced Usage](#advanced-usage)
 
 ## Core Concepts
@@ -332,6 +334,50 @@ Deletes the permalink.
 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)
+}
+```
+
+Options for handling edge cases:
+
+- `onMissingParent`: `'error'` (default) or `'create-as-root'`
+- `onParentConflict`: `'error'` (default), `'update-parent-id'`, or `'ignore'`
+
+## Vault Reference Utilities
+
+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

package/dist/index.cjs

@@ -224,6 +224,16 @@ async function detectFileMimeType(blob) {
   }
   return void 0;
 }
+function sanitizeFileName(name) {
+  if (!name.includes("\0"))
+    return name;
+  const sanitized = name.replace(/\0/g, "");
+  console.warn(
+    "[Vault SDK - WARNING] Null bytes found in file name and were removed.",
+    { original: name, sanitized }
+  );
+  return sanitized;
+}
 function basename(name, separator = "/") {
   if (!name)
     return void 0;
@@ -237,7 +247,7 @@ function getFileName(content) {
 }
 
 const name = "@meistrari/vault-sdk";
-const version = "3.1.1";
+const version = "3.2.1";
 const license = "UNLICENSED";
 const repository = {
 	type: "git",
@@ -265,10 +275,10 @@ const scripts = {
 };
 const dependencies = {
 	"@meistrari/file-type": "22.0.0",
-	"@meistrari/vault-shared": "0.1.0",
+	"@meistrari/vault-shared": "0.1.2",
 	"mime-types": "3.0.1",
 	ofetch: "1.4.1",
-	zod: "3.23.8"
+	zod: "4.3.6"
 };
 const devDependencies = {
 	"@types/bun": "latest",
@@ -603,7 +613,8 @@ class VaultFile {
    */
   static async fromContent(params, options) {
     const { content, config: vaultConfig, upload = false, parentId, onMissingParent, onParentConflict } = params;
-    const name = basename(params.name) ?? getFileName(content);
+    const rawName = basename(params.name) ?? getFileName(content);
+    const name = rawName ? sanitizeFileName(rawName) : rawName;
     const config = resolveConfig(vaultConfig);
     const { vaultUrl, authStrategy } = config;
     const sha256sum = await getFileHash(content);
@@ -686,7 +697,8 @@ class VaultFile {
       onMissingParent,
       onParentConflict
     } = params;
-    const name = basename(params.name);
+    const rawName = basename(params.name);
+    const name = rawName ? sanitizeFileName(rawName) : rawName;
     const config = resolveConfig(vaultConfig);
     const file = new VaultFile({ config, name });
     await file._createFile({
@@ -727,7 +739,8 @@ class VaultFile {
     const config = resolveConfig(vaultConfig);
     const preparedFiles = await Promise.all(
       fileInputs.map(async (input) => {
-        const name = basename(input.name) ?? getFileName(input.content);
+        const rawName = basename(input.name) ?? getFileName(input.content);
+        const name = rawName ? sanitizeFileName(rawName) : rawName;
         const sha256sum = await getFileHash(input.content);
         const mimeType = input.mimeType ?? await detectFileMimeType(input.content);
         const size = input.content.size;
@@ -810,7 +823,8 @@ class VaultFile {
     const { files: fileInputs, config: vaultConfig } = params;
     const config = resolveConfig(vaultConfig);
     const preparedFiles = fileInputs.map((input) => {
-      const name = basename(input.name);
+      const rawName = basename(input.name);
+      const name = rawName ? sanitizeFileName(rawName) : rawName;
       const mimeType = input.contentType || "application/octet-stream";
       const size = input.contentLength;
       return { ...input, name, mimeType, size };

package/dist/index.mjs

@@ -218,6 +218,16 @@ async function detectFileMimeType(blob) {
   }
   return void 0;
 }
+function sanitizeFileName(name) {
+  if (!name.includes("\0"))
+    return name;
+  const sanitized = name.replace(/\0/g, "");
+  console.warn(
+    "[Vault SDK - WARNING] Null bytes found in file name and were removed.",
+    { original: name, sanitized }
+  );
+  return sanitized;
+}
 function basename(name, separator = "/") {
   if (!name)
     return void 0;
@@ -231,7 +241,7 @@ function getFileName(content) {
 }
 
 const name = "@meistrari/vault-sdk";
-const version = "3.1.1";
+const version = "3.2.1";
 const license = "UNLICENSED";
 const repository = {
 	type: "git",
@@ -259,10 +269,10 @@ const scripts = {
 };
 const dependencies = {
 	"@meistrari/file-type": "22.0.0",
-	"@meistrari/vault-shared": "0.1.0",
+	"@meistrari/vault-shared": "0.1.2",
 	"mime-types": "3.0.1",
 	ofetch: "1.4.1",
-	zod: "3.23.8"
+	zod: "4.3.6"
 };
 const devDependencies = {
 	"@types/bun": "latest",
@@ -597,7 +607,8 @@ class VaultFile {
    */
   static async fromContent(params, options) {
     const { content, config: vaultConfig, upload = false, parentId, onMissingParent, onParentConflict } = params;
-    const name = basename(params.name) ?? getFileName(content);
+    const rawName = basename(params.name) ?? getFileName(content);
+    const name = rawName ? sanitizeFileName(rawName) : rawName;
     const config = resolveConfig(vaultConfig);
     const { vaultUrl, authStrategy } = config;
     const sha256sum = await getFileHash(content);
@@ -680,7 +691,8 @@ class VaultFile {
       onMissingParent,
       onParentConflict
     } = params;
-    const name = basename(params.name);
+    const rawName = basename(params.name);
+    const name = rawName ? sanitizeFileName(rawName) : rawName;
     const config = resolveConfig(vaultConfig);
     const file = new VaultFile({ config, name });
     await file._createFile({
@@ -721,7 +733,8 @@ class VaultFile {
     const config = resolveConfig(vaultConfig);
     const preparedFiles = await Promise.all(
       fileInputs.map(async (input) => {
-        const name = basename(input.name) ?? getFileName(input.content);
+        const rawName = basename(input.name) ?? getFileName(input.content);
+        const name = rawName ? sanitizeFileName(rawName) : rawName;
         const sha256sum = await getFileHash(input.content);
         const mimeType = input.mimeType ?? await detectFileMimeType(input.content);
         const size = input.content.size;
@@ -804,7 +817,8 @@ class VaultFile {
     const { files: fileInputs, config: vaultConfig } = params;
     const config = resolveConfig(vaultConfig);
     const preparedFiles = fileInputs.map((input) => {
-      const name = basename(input.name);
+      const rawName = basename(input.name);
+      const name = rawName ? sanitizeFileName(rawName) : rawName;
       const mimeType = input.contentType || "application/octet-stream";
       const size = input.contentLength;
       return { ...input, name, mimeType, size };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/vault-sdk",
-  "version": "3.1.1",
+  "version": "3.2.1",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -28,10 +28,10 @@
   },
   "dependencies": {
     "@meistrari/file-type": "22.0.0",
-    "@meistrari/vault-shared": "0.1.0",
+    "@meistrari/vault-shared": "0.1.2",
     "mime-types": "3.0.1",
     "ofetch": "1.4.1",
-    "zod": "3.23.8"
+    "zod": "4.3.6"
   },
   "devDependencies": {
     "@types/bun": "latest",