@meistrari/vault-sdk 1.5.0 → 1.6.1

package/README.md

@@ -19,8 +19,8 @@ To create a new file in the vault, use `VaultFile.fromContent`:
 
 ```ts
 const vaultFile = await VaultFile.fromContent({
-    name: 'document.txt', // Original filename
     content: new File(['content'], 'document.txt'), // File content
+    name: 'document.txt', // Optional: original filename
     config: {
         vaultUrl,
         authStrategy: new DataTokenAuthStrategy(dataToken)
@@ -63,8 +63,8 @@ const vaultUrl = Bun.env.VAULT_URL ?? 'https://vault.tela.com'
 // Step 1: Create and upload a new file
 const fileContent = Bun.file('path/to/local/file.txt')
 const vaultFile = await VaultFile.fromContent({
-    name: 'file.txt',
     content: fileContent,
+    name: 'file.txt', // Optional: original filename
     config: {
         vaultUrl,
         authStrategy: new DataTokenAuthStrategy(dataToken)
@@ -121,7 +121,7 @@ const fileFromReference = vault.createFromReference('vault://1234567890')
 
 The `useVault` helper provides two methods:
 
-- `createFromContent(name, content)`: Creates a new `VaultFile` instance from a name and content (Blob or File)
+- `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
 
 This helper makes it more convenient to work with multiple vault files using the same configuration.

package/dist/index.cjs

@@ -98,7 +98,7 @@ class Permalink {
   /**
    * Get a new permalink instance from its ID.
    *
-   * @param config - The vault config.
+   * @param vaultConfig - The vault config.
    * @param id - The permalink ID.
    * @returns The permalink.
    */
@@ -116,7 +116,7 @@ class Permalink {
   /**
    * Create a new permalink.
    *
-   * @param config - The vault config.
+   * @param vaultConfig - The vault config.
    * @param params - The parameters for the permalink.
    * @param params.expiresIn - Time, in seconds, the permalink will be valid for.
    * @param params.fileId - The ID of the file to create a permalink for.
@@ -197,11 +197,31 @@ async function detectFileMimeType(blob) {
   if (result?.mime) {
     return result.mime;
   }
+  const text = await blob.text();
+  const trimmedText = text.trim();
+  if (trimmedText.startsWith("{") && trimmedText.endsWith("}") || trimmedText.startsWith("[") && trimmedText.endsWith("]")) {
+    try {
+      JSON.parse(trimmedText);
+      return "application/json";
+    } catch {
+    }
+  }
+  const lines = text.split("\n").slice(0, 5).filter((line) => line.trim() !== "");
+  if (lines.length > 1) {
+    const commaCounts = lines.map((line) => (line.match(/,/g) || []).length);
+    const allSame = commaCounts.every((count) => count === commaCounts[0]);
+    if (allSame && commaCounts[0] > 0) {
+      return "text/csv";
+    }
+  }
+  if (!text.includes("\0") && /^[\s\S]{1,1000}$/.test(text.slice(0, 1e3))) {
+    return "text/plain";
+  }
   return void 0;
 }
 
 const name = "@meistrari/vault-sdk";
-const version = "1.5.0";
+const version = "1.6.1";
 const license = "UNLICENSED";
 const repository = {
 	type: "git",
@@ -273,8 +293,22 @@ const compatibilityDate = "2025-05-19";
 function removeVaultPrefix(url) {
   return url.replace("vault://", "");
 }
-async function wrappedFetch(...params) {
-  const request = new Request(...params);
+function detectMimeTypeFromFilename(filename) {
+  const extension = filename.split(".").pop()?.toLowerCase();
+  if (extension) {
+    const mimeType = mimeTypes.lookup(`.${extension}`);
+    if (mimeType) {
+      return mimeType;
+    }
+  }
+  return void 0;
+}
+async function wrappedFetch(url, requestInit) {
+  const options = {
+    ...requestInit,
+    duplex: requestInit.body instanceof ReadableStream ? "half" : void 0
+  };
+  const request = new Request(url, options);
   request.headers.set("User-Agent", `vault-js-sdk:${packageJson.version}`);
   const response = await fetch(request);
   if (!response.ok) {
@@ -284,9 +318,11 @@ async function wrappedFetch(...params) {
 }
 class VaultFile {
   /**
-   * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended,
-   * instead use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
-   * or {@link VaultFile.fromContent} when preparing a new file for upload.
+   * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended.
+   *
+   * Use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
+   * {@link VaultFile.fromContent} when preparing a new file for upload,
+   * or {@link VaultFile.fromStream} when preparing a new file for streaming upload.
    *
    * @param params - The parameters for the VaultFile constructor
    * @param params.config - The configuration for the VaultFile
@@ -342,12 +378,16 @@ class VaultFile {
         url.searchParams.set(key, value);
       });
     }
-    const response = await wrappedFetch(url, {
+    const requestInit = {
       method,
       body,
       headers,
       signal
-    });
+    };
+    if (body && body instanceof ReadableStream) {
+      requestInit.duplex = "half";
+    }
+    const response = await wrappedFetch(url, requestInit);
     if (response.status === 204 || response.headers.get("content-length") === "0") {
       return null;
     }
@@ -520,6 +560,48 @@ class VaultFile {
     }
     return file;
   }
+  /**
+   * Creates a new VaultFile instance for streaming upload workflows.
+   * This method creates a VaultFile with placeholder content that's optimized for streaming uploads.
+   *
+   * @param params - The parameters for creating a VaultFile for streaming
+   * @param params.name - The name of the file
+   * @param params.contentLength - The size of the content in bytes
+   * @param params.config - The configuration for the VaultFile
+   * @param params.contentType - The MIME type of the content (optional)
+   * @param options - The options for the request
+   * @param options.signal - The signal to abort the request
+   *
+   * @returns A new VaultFile instance ready for streaming upload
+   *
+   * @example
+   * ```ts
+   * // Create VaultFile for streaming
+   * const vaultFile = await VaultFile.fromStream({
+   *     name: 'large-video.mp4',
+   *     contentLength: 100 * 1024 * 1024, // 100MB
+   *     contentType: 'video/mp4',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   *
+   * // Upload using a stream
+   * const fileStream = file.stream()
+   * await vaultFile.uploadStream(fileStream, {
+   *     contentLength: file.size,
+   *     contentType: file.type
+   * })
+   * ```
+   */
+  static async fromStream(params, options) {
+    const { name, contentLength, config: vaultConfig, contentType } = params;
+    const config = resolveConfig(vaultConfig);
+    const file = new VaultFile({ config, name });
+    await file._createFile({
+      size: contentLength,
+      mimeType: contentType || "application/octet-stream"
+    }, { signal: options?.signal });
+    return file;
+  }
   /**
    * Populates the metadata of the file instance.
    * @param options - The options for the request
@@ -687,6 +769,90 @@ class VaultFile {
       return blob;
     return await blobToBase64(blob);
   }
+  /**
+   * Downloads a file from the vault as a stream for memory-efficient processing.
+   *
+   * @param options - The options for the request
+   * @param options.signal - The signal to abort the request
+   *
+   * @returns A ReadableStream that yields chunks of the file data
+   *
+   * @example
+   * ```ts
+   * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', { vaultUrl, authStrategy })
+   * const stream = await vaultFile.downloadStream()
+   *
+   * // Process the stream chunk by chunk
+   * const reader = stream.getReader()
+   * try {
+   *     while (true) {
+   *         const { done, value } = await reader.read()
+   *         if (done) break
+   *         // Process the chunk (Uint8Array)
+   *         console.log('Received chunk of size:', value.length)
+   *     }
+   * } finally {
+   *     reader.releaseLock()
+   * }
+   * ```
+   */
+  async downloadStream(options) {
+    const downloadUrl = await this.getDownloadUrl({ signal: options?.signal });
+    const response = await wrappedFetch(downloadUrl, {
+      method: "GET",
+      signal: options?.signal
+    });
+    if (!response.body) {
+      throw new Error("Response body is not readable");
+    }
+    return response.body;
+  }
+  /**
+   * Uploads a file to the vault using a stream for memory-efficient processing.
+   *
+   * @param stream - The readable stream of file data to upload
+   * @param options - The options for the request
+   * @param options.signal - The signal to abort the request
+   * @param options.contentLength - The total size of the content (required for S3 uploads)
+   * @param options.contentType - The MIME type of the content (will be detected if not provided)
+   *
+   * @throws {Error} If contentLength is not provided
+   * @throws {FetchError} If the upload fails
+   * @returns Promise that resolves when upload is complete
+   *
+   * @example
+   * ```ts
+   * const file = new File(['content'], 'document.txt')
+   * const vaultFile = await VaultFile.fromStream('document.txt', file.size, {
+   *     contentType: file.type,
+   *     config: { vaultUrl, authStrategy }
+   * })
+   *
+   * // Upload using the stream directly
+   * const stream = file.stream()
+   * await vaultFile.uploadStream(stream, {
+   *     contentLength: file.size,
+   *     contentType: file.type
+   * })
+   * ```
+   */
+  async uploadStream(stream, options) {
+    const { contentLength, contentType, signal } = options;
+    if (contentLength === void 0 || contentLength < 0) {
+      throw new Error("contentLength must be provided and non-negative for streaming uploads");
+    }
+    const uploadUrl = await this.getUploadUrl({ signal });
+    const mimeType = contentType ?? this.metadata?.mimeType ?? (this.name ? detectMimeTypeFromFilename(this.name) : void 0) ?? "application/octet-stream";
+    const headers = new Headers();
+    headers.set("Content-Type", mimeType);
+    headers.set("Content-Length", contentLength.toString());
+    await wrappedFetch(uploadUrl, {
+      method: "PUT",
+      body: stream,
+      headers,
+      signal
+    });
+  }
   /**
    * Deletes the file from the vault.
    * @param options - The options for the request
@@ -820,12 +986,20 @@ function convertS3UrlToVaultReference(url) {
 
 function vaultClient(vaultConfig) {
   const config = resolveConfig(vaultConfig);
-  function createFromContent(name, content, options) {
-    return VaultFile.fromContent({
-      name,
-      content,
-      config
-    }, { signal: options?.signal });
+  function createFromContent(nameOrContent, contentOrNameOrOptions, options) {
+    const isOptionsObject = (value) => {
+      return typeof value === "object" && value !== null && !(value instanceof Blob) && !(value instanceof File);
+    };
+    if (typeof nameOrContent === "string") {
+      const name2 = nameOrContent;
+      const content2 = contentOrNameOrOptions;
+      const signal2 = options?.signal;
+      return VaultFile.fromContent({ content: content2, name: name2, config }, { signal: signal2 });
+    }
+    const content = nameOrContent;
+    const name = typeof contentOrNameOrOptions === "string" ? contentOrNameOrOptions : void 0;
+    const signal = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.signal : options?.signal;
+    return VaultFile.fromContent({ content, name, config }, { signal });
   }
   function createFromReference(reference, options) {
     return VaultFile.fromVaultReference({
@@ -833,7 +1007,15 @@ function vaultClient(vaultConfig) {
       config
     }, { signal: options?.signal });
   }
-  return { createFromContent, createFromReference };
+  async function createFromStream(name, contentLength, options) {
+    return VaultFile.fromStream({
+      name,
+      contentLength,
+      config,
+      contentType: options?.contentType
+    }, { signal: options?.signal });
+  }
+  return { createFromContent, createFromReference, createFromStream };
 }
 
 exports.APIKeyAuthStrategy = APIKeyAuthStrategy;

package/dist/index.d.cts

@@ -45,7 +45,7 @@ declare class Permalink {
     /**
      * Get a new permalink instance from its ID.
      *
-     * @param config - The vault config.
+     * @param vaultConfig - The vault config.
      * @param id - The permalink ID.
      * @returns The permalink.
      */
@@ -53,7 +53,7 @@ declare class Permalink {
     /**
      * Create a new permalink.
      *
-     * @param config - The vault config.
+     * @param vaultConfig - The vault config.
      * @param params - The parameters for the permalink.
      * @param params.expiresIn - Time, in seconds, the permalink will be valid for.
      * @param params.fileId - The ID of the file to create a permalink for.
@@ -114,9 +114,11 @@ declare class VaultFile {
     } | undefined;
     private readonly baseUrl;
     /**
-     * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended,
-     * instead use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
-     * or {@link VaultFile.fromContent} when preparing a new file for upload.
+     * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended.
+     *
+     * Use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
+     * {@link VaultFile.fromContent} when preparing a new file for upload,
+     * or {@link VaultFile.fromStream} when preparing a new file for streaming upload.
      *
      * @param params - The parameters for the VaultFile constructor
      * @param params.config - The configuration for the VaultFile
@@ -247,13 +249,53 @@ declare class VaultFile {
      * ```
      */
     static fromContent(params: {
-        name: string;
         content: Blob | File;
         config: VaultConfig;
+        name?: string;
         upload?: boolean;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
+    /**
+     * Creates a new VaultFile instance for streaming upload workflows.
+     * This method creates a VaultFile with placeholder content that's optimized for streaming uploads.
+     *
+     * @param params - The parameters for creating a VaultFile for streaming
+     * @param params.name - The name of the file
+     * @param params.contentLength - The size of the content in bytes
+     * @param params.config - The configuration for the VaultFile
+     * @param params.contentType - The MIME type of the content (optional)
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     *
+     * @returns A new VaultFile instance ready for streaming upload
+     *
+     * @example
+     * ```ts
+     * // Create VaultFile for streaming
+     * const vaultFile = await VaultFile.fromStream({
+     *     name: 'large-video.mp4',
+     *     contentLength: 100 * 1024 * 1024, // 100MB
+     *     contentType: 'video/mp4',
+     *     config: { vaultUrl, authStrategy }
+     * })
+     *
+     * // Upload using a stream
+     * const fileStream = file.stream()
+     * await vaultFile.uploadStream(fileStream, {
+     *     contentLength: file.size,
+     *     contentType: file.type
+     * })
+     * ```
+     */
+    static fromStream(params: {
+        name: string;
+        contentLength: number;
+        config: VaultConfig;
+        contentType?: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<VaultFile>;
     /**
      * Populates the metadata of the file instance.
      * @param options - The options for the request
@@ -364,6 +406,70 @@ declare class VaultFile {
     download(responseType: 'base64', options?: {
         signal?: AbortSignal;
     }): Promise<string>;
+    /**
+     * Downloads a file from the vault as a stream for memory-efficient processing.
+     *
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     *
+     * @returns A ReadableStream that yields chunks of the file data
+     *
+     * @example
+     * ```ts
+     * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', { vaultUrl, authStrategy })
+     * const stream = await vaultFile.downloadStream()
+     *
+     * // Process the stream chunk by chunk
+     * const reader = stream.getReader()
+     * try {
+     *     while (true) {
+     *         const { done, value } = await reader.read()
+     *         if (done) break
+     *         // Process the chunk (Uint8Array)
+     *         console.log('Received chunk of size:', value.length)
+     *     }
+     * } finally {
+     *     reader.releaseLock()
+     * }
+     * ```
+     */
+    downloadStream(options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Uploads a file to the vault using a stream for memory-efficient processing.
+     *
+     * @param stream - The readable stream of file data to upload
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     * @param options.contentLength - The total size of the content (required for S3 uploads)
+     * @param options.contentType - The MIME type of the content (will be detected if not provided)
+     *
+     * @throws {Error} If contentLength is not provided
+     * @throws {FetchError} If the upload fails
+     * @returns Promise that resolves when upload is complete
+     *
+     * @example
+     * ```ts
+     * const file = new File(['content'], 'document.txt')
+     * const vaultFile = await VaultFile.fromStream('document.txt', file.size, {
+     *     contentType: file.type,
+     *     config: { vaultUrl, authStrategy }
+     * })
+     *
+     * // Upload using the stream directly
+     * const stream = file.stream()
+     * await vaultFile.uploadStream(stream, {
+     *     contentLength: file.size,
+     *     contentType: file.type
+     * })
+     * ```
+     */
+    uploadStream(stream: ReadableStream<Uint8Array>, options: {
+        signal?: AbortSignal;
+        contentLength: number;
+        contentType?: string;
+    }): Promise<void>;
     /**
      * Deletes the file from the vault.
      * @param options - The options for the request
@@ -430,10 +536,22 @@ declare function extractVaultFileIdFromS3Url(url: string): string | null;
 declare function convertS3UrlToVaultReference(url: string): string | null;
 
 declare function vaultClient(vaultConfig: VaultConfig): {
-    createFromContent: (name: string, content: Blob | File, options?: {
+    createFromContent: {
+        (name: string, content: Blob | File, options?: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+        (content: Blob | File, name?: string, options?: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+        (content: Blob | File, options: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+    };
+    createFromReference: (reference: string, options?: {
         signal?: AbortSignal;
     }) => Promise<VaultFile>;
-    createFromReference: (reference: string, options?: {
+    createFromStream: (name: string, contentLength: number, options?: {
+        contentType?: string;
         signal?: AbortSignal;
     }) => Promise<VaultFile>;
 };

package/dist/index.d.mts

@@ -45,7 +45,7 @@ declare class Permalink {
     /**
      * Get a new permalink instance from its ID.
      *
-     * @param config - The vault config.
+     * @param vaultConfig - The vault config.
      * @param id - The permalink ID.
      * @returns The permalink.
      */
@@ -53,7 +53,7 @@ declare class Permalink {
     /**
      * Create a new permalink.
      *
-     * @param config - The vault config.
+     * @param vaultConfig - The vault config.
      * @param params - The parameters for the permalink.
      * @param params.expiresIn - Time, in seconds, the permalink will be valid for.
      * @param params.fileId - The ID of the file to create a permalink for.
@@ -114,9 +114,11 @@ declare class VaultFile {
     } | undefined;
     private readonly baseUrl;
     /**
-     * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended,
-     * instead use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
-     * or {@link VaultFile.fromContent} when preparing a new file for upload.
+     * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended.
+     *
+     * Use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
+     * {@link VaultFile.fromContent} when preparing a new file for upload,
+     * or {@link VaultFile.fromStream} when preparing a new file for streaming upload.
      *
      * @param params - The parameters for the VaultFile constructor
      * @param params.config - The configuration for the VaultFile
@@ -247,13 +249,53 @@ declare class VaultFile {
      * ```
      */
     static fromContent(params: {
-        name: string;
         content: Blob | File;
         config: VaultConfig;
+        name?: string;
         upload?: boolean;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
+    /**
+     * Creates a new VaultFile instance for streaming upload workflows.
+     * This method creates a VaultFile with placeholder content that's optimized for streaming uploads.
+     *
+     * @param params - The parameters for creating a VaultFile for streaming
+     * @param params.name - The name of the file
+     * @param params.contentLength - The size of the content in bytes
+     * @param params.config - The configuration for the VaultFile
+     * @param params.contentType - The MIME type of the content (optional)
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     *
+     * @returns A new VaultFile instance ready for streaming upload
+     *
+     * @example
+     * ```ts
+     * // Create VaultFile for streaming
+     * const vaultFile = await VaultFile.fromStream({
+     *     name: 'large-video.mp4',
+     *     contentLength: 100 * 1024 * 1024, // 100MB
+     *     contentType: 'video/mp4',
+     *     config: { vaultUrl, authStrategy }
+     * })
+     *
+     * // Upload using a stream
+     * const fileStream = file.stream()
+     * await vaultFile.uploadStream(fileStream, {
+     *     contentLength: file.size,
+     *     contentType: file.type
+     * })
+     * ```
+     */
+    static fromStream(params: {
+        name: string;
+        contentLength: number;
+        config: VaultConfig;
+        contentType?: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<VaultFile>;
     /**
      * Populates the metadata of the file instance.
      * @param options - The options for the request
@@ -364,6 +406,70 @@ declare class VaultFile {
     download(responseType: 'base64', options?: {
         signal?: AbortSignal;
     }): Promise<string>;
+    /**
+     * Downloads a file from the vault as a stream for memory-efficient processing.
+     *
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     *
+     * @returns A ReadableStream that yields chunks of the file data
+     *
+     * @example
+     * ```ts
+     * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', { vaultUrl, authStrategy })
+     * const stream = await vaultFile.downloadStream()
+     *
+     * // Process the stream chunk by chunk
+     * const reader = stream.getReader()
+     * try {
+     *     while (true) {
+     *         const { done, value } = await reader.read()
+     *         if (done) break
+     *         // Process the chunk (Uint8Array)
+     *         console.log('Received chunk of size:', value.length)
+     *     }
+     * } finally {
+     *     reader.releaseLock()
+     * }
+     * ```
+     */
+    downloadStream(options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Uploads a file to the vault using a stream for memory-efficient processing.
+     *
+     * @param stream - The readable stream of file data to upload
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     * @param options.contentLength - The total size of the content (required for S3 uploads)
+     * @param options.contentType - The MIME type of the content (will be detected if not provided)
+     *
+     * @throws {Error} If contentLength is not provided
+     * @throws {FetchError} If the upload fails
+     * @returns Promise that resolves when upload is complete
+     *
+     * @example
+     * ```ts
+     * const file = new File(['content'], 'document.txt')
+     * const vaultFile = await VaultFile.fromStream('document.txt', file.size, {
+     *     contentType: file.type,
+     *     config: { vaultUrl, authStrategy }
+     * })
+     *
+     * // Upload using the stream directly
+     * const stream = file.stream()
+     * await vaultFile.uploadStream(stream, {
+     *     contentLength: file.size,
+     *     contentType: file.type
+     * })
+     * ```
+     */
+    uploadStream(stream: ReadableStream<Uint8Array>, options: {
+        signal?: AbortSignal;
+        contentLength: number;
+        contentType?: string;
+    }): Promise<void>;
     /**
      * Deletes the file from the vault.
      * @param options - The options for the request
@@ -430,10 +536,22 @@ declare function extractVaultFileIdFromS3Url(url: string): string | null;
 declare function convertS3UrlToVaultReference(url: string): string | null;
 
 declare function vaultClient(vaultConfig: VaultConfig): {
-    createFromContent: (name: string, content: Blob | File, options?: {
+    createFromContent: {
+        (name: string, content: Blob | File, options?: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+        (content: Blob | File, name?: string, options?: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+        (content: Blob | File, options: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+    };
+    createFromReference: (reference: string, options?: {
         signal?: AbortSignal;
     }) => Promise<VaultFile>;
-    createFromReference: (reference: string, options?: {
+    createFromStream: (name: string, contentLength: number, options?: {
+        contentType?: string;
         signal?: AbortSignal;
     }) => Promise<VaultFile>;
 };

package/dist/index.d.ts

@@ -45,7 +45,7 @@ declare class Permalink {
     /**
      * Get a new permalink instance from its ID.
      *
-     * @param config - The vault config.
+     * @param vaultConfig - The vault config.
      * @param id - The permalink ID.
      * @returns The permalink.
      */
@@ -53,7 +53,7 @@ declare class Permalink {
     /**
      * Create a new permalink.
      *
-     * @param config - The vault config.
+     * @param vaultConfig - The vault config.
      * @param params - The parameters for the permalink.
      * @param params.expiresIn - Time, in seconds, the permalink will be valid for.
      * @param params.fileId - The ID of the file to create a permalink for.
@@ -114,9 +114,11 @@ declare class VaultFile {
     } | undefined;
     private readonly baseUrl;
     /**
-     * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended,
-     * instead use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
-     * or {@link VaultFile.fromContent} when preparing a new file for upload.
+     * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended.
+     *
+     * Use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
+     * {@link VaultFile.fromContent} when preparing a new file for upload,
+     * or {@link VaultFile.fromStream} when preparing a new file for streaming upload.
      *
      * @param params - The parameters for the VaultFile constructor
      * @param params.config - The configuration for the VaultFile
@@ -247,13 +249,53 @@ declare class VaultFile {
      * ```
      */
     static fromContent(params: {
-        name: string;
         content: Blob | File;
         config: VaultConfig;
+        name?: string;
         upload?: boolean;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
+    /**
+     * Creates a new VaultFile instance for streaming upload workflows.
+     * This method creates a VaultFile with placeholder content that's optimized for streaming uploads.
+     *
+     * @param params - The parameters for creating a VaultFile for streaming
+     * @param params.name - The name of the file
+     * @param params.contentLength - The size of the content in bytes
+     * @param params.config - The configuration for the VaultFile
+     * @param params.contentType - The MIME type of the content (optional)
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     *
+     * @returns A new VaultFile instance ready for streaming upload
+     *
+     * @example
+     * ```ts
+     * // Create VaultFile for streaming
+     * const vaultFile = await VaultFile.fromStream({
+     *     name: 'large-video.mp4',
+     *     contentLength: 100 * 1024 * 1024, // 100MB
+     *     contentType: 'video/mp4',
+     *     config: { vaultUrl, authStrategy }
+     * })
+     *
+     * // Upload using a stream
+     * const fileStream = file.stream()
+     * await vaultFile.uploadStream(fileStream, {
+     *     contentLength: file.size,
+     *     contentType: file.type
+     * })
+     * ```
+     */
+    static fromStream(params: {
+        name: string;
+        contentLength: number;
+        config: VaultConfig;
+        contentType?: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<VaultFile>;
     /**
      * Populates the metadata of the file instance.
      * @param options - The options for the request
@@ -364,6 +406,70 @@ declare class VaultFile {
     download(responseType: 'base64', options?: {
         signal?: AbortSignal;
     }): Promise<string>;
+    /**
+     * Downloads a file from the vault as a stream for memory-efficient processing.
+     *
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     *
+     * @returns A ReadableStream that yields chunks of the file data
+     *
+     * @example
+     * ```ts
+     * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', { vaultUrl, authStrategy })
+     * const stream = await vaultFile.downloadStream()
+     *
+     * // Process the stream chunk by chunk
+     * const reader = stream.getReader()
+     * try {
+     *     while (true) {
+     *         const { done, value } = await reader.read()
+     *         if (done) break
+     *         // Process the chunk (Uint8Array)
+     *         console.log('Received chunk of size:', value.length)
+     *     }
+     * } finally {
+     *     reader.releaseLock()
+     * }
+     * ```
+     */
+    downloadStream(options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Uploads a file to the vault using a stream for memory-efficient processing.
+     *
+     * @param stream - The readable stream of file data to upload
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     * @param options.contentLength - The total size of the content (required for S3 uploads)
+     * @param options.contentType - The MIME type of the content (will be detected if not provided)
+     *
+     * @throws {Error} If contentLength is not provided
+     * @throws {FetchError} If the upload fails
+     * @returns Promise that resolves when upload is complete
+     *
+     * @example
+     * ```ts
+     * const file = new File(['content'], 'document.txt')
+     * const vaultFile = await VaultFile.fromStream('document.txt', file.size, {
+     *     contentType: file.type,
+     *     config: { vaultUrl, authStrategy }
+     * })
+     *
+     * // Upload using the stream directly
+     * const stream = file.stream()
+     * await vaultFile.uploadStream(stream, {
+     *     contentLength: file.size,
+     *     contentType: file.type
+     * })
+     * ```
+     */
+    uploadStream(stream: ReadableStream<Uint8Array>, options: {
+        signal?: AbortSignal;
+        contentLength: number;
+        contentType?: string;
+    }): Promise<void>;
     /**
      * Deletes the file from the vault.
      * @param options - The options for the request
@@ -430,10 +536,22 @@ declare function extractVaultFileIdFromS3Url(url: string): string | null;
 declare function convertS3UrlToVaultReference(url: string): string | null;
 
 declare function vaultClient(vaultConfig: VaultConfig): {
-    createFromContent: (name: string, content: Blob | File, options?: {
+    createFromContent: {
+        (name: string, content: Blob | File, options?: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+        (content: Blob | File, name?: string, options?: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+        (content: Blob | File, options: {
+            signal?: AbortSignal;
+        }): Promise<VaultFile>;
+    };
+    createFromReference: (reference: string, options?: {
         signal?: AbortSignal;
     }) => Promise<VaultFile>;
-    createFromReference: (reference: string, options?: {
+    createFromStream: (name: string, contentLength: number, options?: {
+        contentType?: string;
         signal?: AbortSignal;
     }) => Promise<VaultFile>;
 };

package/dist/index.mjs

@@ -96,7 +96,7 @@ class Permalink {
   /**
    * Get a new permalink instance from its ID.
    *
-   * @param config - The vault config.
+   * @param vaultConfig - The vault config.
    * @param id - The permalink ID.
    * @returns The permalink.
    */
@@ -114,7 +114,7 @@ class Permalink {
   /**
    * Create a new permalink.
    *
-   * @param config - The vault config.
+   * @param vaultConfig - The vault config.
    * @param params - The parameters for the permalink.
    * @param params.expiresIn - Time, in seconds, the permalink will be valid for.
    * @param params.fileId - The ID of the file to create a permalink for.
@@ -195,11 +195,31 @@ async function detectFileMimeType(blob) {
   if (result?.mime) {
     return result.mime;
   }
+  const text = await blob.text();
+  const trimmedText = text.trim();
+  if (trimmedText.startsWith("{") && trimmedText.endsWith("}") || trimmedText.startsWith("[") && trimmedText.endsWith("]")) {
+    try {
+      JSON.parse(trimmedText);
+      return "application/json";
+    } catch {
+    }
+  }
+  const lines = text.split("\n").slice(0, 5).filter((line) => line.trim() !== "");
+  if (lines.length > 1) {
+    const commaCounts = lines.map((line) => (line.match(/,/g) || []).length);
+    const allSame = commaCounts.every((count) => count === commaCounts[0]);
+    if (allSame && commaCounts[0] > 0) {
+      return "text/csv";
+    }
+  }
+  if (!text.includes("\0") && /^[\s\S]{1,1000}$/.test(text.slice(0, 1e3))) {
+    return "text/plain";
+  }
   return void 0;
 }
 
 const name = "@meistrari/vault-sdk";
-const version = "1.5.0";
+const version = "1.6.1";
 const license = "UNLICENSED";
 const repository = {
 	type: "git",
@@ -271,8 +291,22 @@ const compatibilityDate = "2025-05-19";
 function removeVaultPrefix(url) {
   return url.replace("vault://", "");
 }
-async function wrappedFetch(...params) {
-  const request = new Request(...params);
+function detectMimeTypeFromFilename(filename) {
+  const extension = filename.split(".").pop()?.toLowerCase();
+  if (extension) {
+    const mimeType = lookup(`.${extension}`);
+    if (mimeType) {
+      return mimeType;
+    }
+  }
+  return void 0;
+}
+async function wrappedFetch(url, requestInit) {
+  const options = {
+    ...requestInit,
+    duplex: requestInit.body instanceof ReadableStream ? "half" : void 0
+  };
+  const request = new Request(url, options);
   request.headers.set("User-Agent", `vault-js-sdk:${packageJson.version}`);
   const response = await fetch(request);
   if (!response.ok) {
@@ -282,9 +316,11 @@ async function wrappedFetch(...params) {
 }
 class VaultFile {
   /**
-   * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended,
-   * instead use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
-   * or {@link VaultFile.fromContent} when preparing a new file for upload.
+   * Constructs a new VaultFile instance. Direct usage of the constructor is not recommended.
+   *
+   * Use the static methods {@link VaultFile.fromVaultReference} when dealing with an existing file in the vault,
+   * {@link VaultFile.fromContent} when preparing a new file for upload,
+   * or {@link VaultFile.fromStream} when preparing a new file for streaming upload.
    *
    * @param params - The parameters for the VaultFile constructor
    * @param params.config - The configuration for the VaultFile
@@ -340,12 +376,16 @@ class VaultFile {
         url.searchParams.set(key, value);
       });
     }
-    const response = await wrappedFetch(url, {
+    const requestInit = {
       method,
       body,
       headers,
       signal
-    });
+    };
+    if (body && body instanceof ReadableStream) {
+      requestInit.duplex = "half";
+    }
+    const response = await wrappedFetch(url, requestInit);
     if (response.status === 204 || response.headers.get("content-length") === "0") {
       return null;
     }
@@ -518,6 +558,48 @@ class VaultFile {
     }
     return file;
   }
+  /**
+   * Creates a new VaultFile instance for streaming upload workflows.
+   * This method creates a VaultFile with placeholder content that's optimized for streaming uploads.
+   *
+   * @param params - The parameters for creating a VaultFile for streaming
+   * @param params.name - The name of the file
+   * @param params.contentLength - The size of the content in bytes
+   * @param params.config - The configuration for the VaultFile
+   * @param params.contentType - The MIME type of the content (optional)
+   * @param options - The options for the request
+   * @param options.signal - The signal to abort the request
+   *
+   * @returns A new VaultFile instance ready for streaming upload
+   *
+   * @example
+   * ```ts
+   * // Create VaultFile for streaming
+   * const vaultFile = await VaultFile.fromStream({
+   *     name: 'large-video.mp4',
+   *     contentLength: 100 * 1024 * 1024, // 100MB
+   *     contentType: 'video/mp4',
+   *     config: { vaultUrl, authStrategy }
+   * })
+   *
+   * // Upload using a stream
+   * const fileStream = file.stream()
+   * await vaultFile.uploadStream(fileStream, {
+   *     contentLength: file.size,
+   *     contentType: file.type
+   * })
+   * ```
+   */
+  static async fromStream(params, options) {
+    const { name, contentLength, config: vaultConfig, contentType } = params;
+    const config = resolveConfig(vaultConfig);
+    const file = new VaultFile({ config, name });
+    await file._createFile({
+      size: contentLength,
+      mimeType: contentType || "application/octet-stream"
+    }, { signal: options?.signal });
+    return file;
+  }
   /**
    * Populates the metadata of the file instance.
    * @param options - The options for the request
@@ -685,6 +767,90 @@ class VaultFile {
       return blob;
     return await blobToBase64(blob);
   }
+  /**
+   * Downloads a file from the vault as a stream for memory-efficient processing.
+   *
+   * @param options - The options for the request
+   * @param options.signal - The signal to abort the request
+   *
+   * @returns A ReadableStream that yields chunks of the file data
+   *
+   * @example
+   * ```ts
+   * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', { vaultUrl, authStrategy })
+   * const stream = await vaultFile.downloadStream()
+   *
+   * // Process the stream chunk by chunk
+   * const reader = stream.getReader()
+   * try {
+   *     while (true) {
+   *         const { done, value } = await reader.read()
+   *         if (done) break
+   *         // Process the chunk (Uint8Array)
+   *         console.log('Received chunk of size:', value.length)
+   *     }
+   * } finally {
+   *     reader.releaseLock()
+   * }
+   * ```
+   */
+  async downloadStream(options) {
+    const downloadUrl = await this.getDownloadUrl({ signal: options?.signal });
+    const response = await wrappedFetch(downloadUrl, {
+      method: "GET",
+      signal: options?.signal
+    });
+    if (!response.body) {
+      throw new Error("Response body is not readable");
+    }
+    return response.body;
+  }
+  /**
+   * Uploads a file to the vault using a stream for memory-efficient processing.
+   *
+   * @param stream - The readable stream of file data to upload
+   * @param options - The options for the request
+   * @param options.signal - The signal to abort the request
+   * @param options.contentLength - The total size of the content (required for S3 uploads)
+   * @param options.contentType - The MIME type of the content (will be detected if not provided)
+   *
+   * @throws {Error} If contentLength is not provided
+   * @throws {FetchError} If the upload fails
+   * @returns Promise that resolves when upload is complete
+   *
+   * @example
+   * ```ts
+   * const file = new File(['content'], 'document.txt')
+   * const vaultFile = await VaultFile.fromStream('document.txt', file.size, {
+   *     contentType: file.type,
+   *     config: { vaultUrl, authStrategy }
+   * })
+   *
+   * // Upload using the stream directly
+   * const stream = file.stream()
+   * await vaultFile.uploadStream(stream, {
+   *     contentLength: file.size,
+   *     contentType: file.type
+   * })
+   * ```
+   */
+  async uploadStream(stream, options) {
+    const { contentLength, contentType, signal } = options;
+    if (contentLength === void 0 || contentLength < 0) {
+      throw new Error("contentLength must be provided and non-negative for streaming uploads");
+    }
+    const uploadUrl = await this.getUploadUrl({ signal });
+    const mimeType = contentType ?? this.metadata?.mimeType ?? (this.name ? detectMimeTypeFromFilename(this.name) : void 0) ?? "application/octet-stream";
+    const headers = new Headers();
+    headers.set("Content-Type", mimeType);
+    headers.set("Content-Length", contentLength.toString());
+    await wrappedFetch(uploadUrl, {
+      method: "PUT",
+      body: stream,
+      headers,
+      signal
+    });
+  }
   /**
    * Deletes the file from the vault.
    * @param options - The options for the request
@@ -818,12 +984,20 @@ function convertS3UrlToVaultReference(url) {
 
 function vaultClient(vaultConfig) {
   const config = resolveConfig(vaultConfig);
-  function createFromContent(name, content, options) {
-    return VaultFile.fromContent({
-      name,
-      content,
-      config
-    }, { signal: options?.signal });
+  function createFromContent(nameOrContent, contentOrNameOrOptions, options) {
+    const isOptionsObject = (value) => {
+      return typeof value === "object" && value !== null && !(value instanceof Blob) && !(value instanceof File);
+    };
+    if (typeof nameOrContent === "string") {
+      const name2 = nameOrContent;
+      const content2 = contentOrNameOrOptions;
+      const signal2 = options?.signal;
+      return VaultFile.fromContent({ content: content2, name: name2, config }, { signal: signal2 });
+    }
+    const content = nameOrContent;
+    const name = typeof contentOrNameOrOptions === "string" ? contentOrNameOrOptions : void 0;
+    const signal = isOptionsObject(contentOrNameOrOptions) ? contentOrNameOrOptions.signal : options?.signal;
+    return VaultFile.fromContent({ content, name, config }, { signal });
   }
   function createFromReference(reference, options) {
     return VaultFile.fromVaultReference({
@@ -831,7 +1005,15 @@ function vaultClient(vaultConfig) {
       config
     }, { signal: options?.signal });
   }
-  return { createFromContent, createFromReference };
+  async function createFromStream(name, contentLength, options) {
+    return VaultFile.fromStream({
+      name,
+      contentLength,
+      config,
+      contentType: options?.contentType
+    }, { signal: options?.signal });
+  }
+  return { createFromContent, createFromReference, createFromStream };
 }
 
 export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, isS3UrlExpired, isVaultFileS3Url, vaultClient };

package/package.json

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