@meistrari/vault-sdk 1.4.3 → 1.6.0

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
@@ -254,6 +256,46 @@ declare class VaultFile {
     }, 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
@@ -399,6 +505,36 @@ declare class VaultFile {
     }): Promise<Permalink[]>;
 }
 
+/**
+ * Checks if an Amazon S3 signed URL has expired
+ * @param url - The S3 URL to check for expiration
+ * @returns true if the URL is expired, false if it's still valid or not an S3 signed URL
+ * @example
+ * const expired = isS3UrlExpired('https://vault-prod.s3.amazonaws.com/file?X-Amz-Date=20240101T000000Z&X-Amz-Expires=3600')
+ */
+declare function isS3UrlExpired(url: string): boolean;
+/**
+ * Checks if a URL is a valid S3 vault URL
+ * @param url - The S3 URL to check
+ * @returns true if the URL is a valid S3 vault URL, false otherwise
+ */
+declare function isVaultFileS3Url(url: string): boolean;
+/**
+ * Detects if a URL is an expired S3 vault URL and extracts the vault file ID
+ * Returns null if not a vault S3 URL, not expired, or extraction fails
+ */
+declare function extractVaultFileIdFromS3Url(url: string): string | null;
+/**
+ * Converts an S3 vault URL to a vault reference format
+ * Extracts the vault file ID from the S3 URL path and formats it as vault://[fileId]
+ * @param url - The S3 vault URL to convert
+ * @returns A vault reference string (vault://[fileId]) if successful, null if the URL is not a valid vault S3 URL
+ * @example
+ * const ref = convertS3UrlToVaultReference('https://vault-prod.s3.amazonaws.com/workspace123/2fce574083da49fe3f10b32205893ec0bb024fe1c7673fa54927fdfe1d0db9d6?...')
+ * // Returns: 'vault://2fce574083da49fe3f10b32205893ec0bb024fe1c7673fa54927fdfe1d0db9d6'
+ */
+declare function convertS3UrlToVaultReference(url: string): string | null;
+
 declare function vaultClient(vaultConfig: VaultConfig): {
     createFromContent: (name: string, content: Blob | File, options?: {
         signal?: AbortSignal;
@@ -406,7 +542,11 @@ declare function vaultClient(vaultConfig: VaultConfig): {
     createFromReference: (reference: string, options?: {
         signal?: AbortSignal;
     }) => Promise<VaultFile>;
+    createFromStream: (name: string, contentLength: number, options?: {
+        contentType?: string;
+        signal?: AbortSignal;
+    }) => Promise<VaultFile>;
 };
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, vaultClient };
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, isS3UrlExpired, isVaultFileS3Url, vaultClient };
 export type { AuthStrategy, VaultConfig };

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
@@ -254,6 +256,46 @@ declare class VaultFile {
     }, 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
@@ -399,6 +505,36 @@ declare class VaultFile {
     }): Promise<Permalink[]>;
 }
 
+/**
+ * Checks if an Amazon S3 signed URL has expired
+ * @param url - The S3 URL to check for expiration
+ * @returns true if the URL is expired, false if it's still valid or not an S3 signed URL
+ * @example
+ * const expired = isS3UrlExpired('https://vault-prod.s3.amazonaws.com/file?X-Amz-Date=20240101T000000Z&X-Amz-Expires=3600')
+ */
+declare function isS3UrlExpired(url: string): boolean;
+/**
+ * Checks if a URL is a valid S3 vault URL
+ * @param url - The S3 URL to check
+ * @returns true if the URL is a valid S3 vault URL, false otherwise
+ */
+declare function isVaultFileS3Url(url: string): boolean;
+/**
+ * Detects if a URL is an expired S3 vault URL and extracts the vault file ID
+ * Returns null if not a vault S3 URL, not expired, or extraction fails
+ */
+declare function extractVaultFileIdFromS3Url(url: string): string | null;
+/**
+ * Converts an S3 vault URL to a vault reference format
+ * Extracts the vault file ID from the S3 URL path and formats it as vault://[fileId]
+ * @param url - The S3 vault URL to convert
+ * @returns A vault reference string (vault://[fileId]) if successful, null if the URL is not a valid vault S3 URL
+ * @example
+ * const ref = convertS3UrlToVaultReference('https://vault-prod.s3.amazonaws.com/workspace123/2fce574083da49fe3f10b32205893ec0bb024fe1c7673fa54927fdfe1d0db9d6?...')
+ * // Returns: 'vault://2fce574083da49fe3f10b32205893ec0bb024fe1c7673fa54927fdfe1d0db9d6'
+ */
+declare function convertS3UrlToVaultReference(url: string): string | null;
+
 declare function vaultClient(vaultConfig: VaultConfig): {
     createFromContent: (name: string, content: Blob | File, options?: {
         signal?: AbortSignal;
@@ -406,7 +542,11 @@ declare function vaultClient(vaultConfig: VaultConfig): {
     createFromReference: (reference: string, options?: {
         signal?: AbortSignal;
     }) => Promise<VaultFile>;
+    createFromStream: (name: string, contentLength: number, options?: {
+        contentType?: string;
+        signal?: AbortSignal;
+    }) => Promise<VaultFile>;
 };
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, vaultClient };
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, isS3UrlExpired, isVaultFileS3Url, vaultClient };
 export type { AuthStrategy, VaultConfig };