@meistrari/vault-sdk 1.8.3 → 2.0.0

package/dist/index.d.cts

@@ -88,6 +88,22 @@ type VaultFileParams = {
     config: VaultConfig;
 };
 type OnMissingParent = 'error' | 'create-as-root';
+type OnParentConflict = 'error' | 'update-parent-id' | 'ignore';
+/**
+ * Parameters for updating metadata of a VaultFile.
+ */
+interface VaultFileUpdateMetadataParams {
+    /** The new name to assign to the file. If not provided, the name will not be changed. */
+    name?: string;
+}
+type BulkFileInput = {
+    content: Blob | File;
+    name?: string;
+    mimeType?: string;
+    parentId?: string;
+    onMissingParent?: OnMissingParent;
+    onParentConflict?: OnParentConflict;
+};
 /**
  * Represents a file in the vault and allows interacting with it.
  *
@@ -154,6 +170,7 @@ declare class VaultFile {
      * @param metadata.mimeType - The mime type of the file
      * @param metadata.parentId - The ID of the parent file for hierarchical file relationships
      * @param metadata.onMissingParent - What to do if the parent file does not exist or has been deleted
+     * @param metadata.onParentConflict - What to do if the file already exists as an active child of another file
      * @param options - The options for the request
      * @param options.signal - The signal to abort the request
      *
@@ -219,6 +236,7 @@ declare class VaultFile {
      * @param params.upload - Whether to upload the file (default: false)
      * @param params.parentId - The ID of the parent file for hierarchical file relationships
      * @param params.onMissingParent - What to do if the parent file does not exist or has been deleted
+     * @param params.onParentConflict - What to do if the file already exists as an active child of another file
      * @param options - The options for the request
      * @param options.signal - The signal to abort the request
      *
@@ -278,6 +296,7 @@ declare class VaultFile {
         upload?: boolean;
         parentId?: string;
         onMissingParent?: OnMissingParent;
+        onParentConflict?: OnParentConflict;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
@@ -292,6 +311,7 @@ declare class VaultFile {
      * @param params.contentType - The MIME type of the content (optional)
      * @param params.parentId - The ID of the parent file for hierarchical file relationships
      * @param params.onMissingParent - What to do if the parent file does not exist or has been deleted
+     * @param params.onParentConflict - What to do if the file already exists as an active child of another file
      * @param options - The options for the request
      * @param options.signal - The signal to abort the request
      *
@@ -334,9 +354,41 @@ declare class VaultFile {
         contentType?: string;
         parentId?: string;
         onMissingParent?: OnMissingParent;
+        onParentConflict?: OnParentConflict;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
+    /**
+     * Creates multiple VaultFile instances from given content in a single request.
+     *
+     * @param params - Parameters for creating VaultFiles from content
+     * @param params.files - Array of file inputs with content and optional metadata
+     * @param params.config - The configuration for the VaultFiles
+     * @param params.upload - Whether to upload all files (default: false)
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     *
+     * @returns Array of new VaultFile instances
+     *
+     * @example
+     * ```ts
+     * const files = await VaultFile.fromContentBulk({
+     *     files: [
+     *         { content: blob1, name: 'file1.txt' },
+     *         { content: blob2, name: 'file2.txt', parentId: 'parent-id' },
+     *     ],
+     *     config: { vaultUrl, authStrategy },
+     *     upload: true
+     * })
+     * ```
+     */
+    static fromContentBulk(params: {
+        files: BulkFileInput[];
+        config: VaultConfig;
+        upload?: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<VaultFile[]>;
     /**
      * Fetches and populates the metadata fields for this VaultFile instance.
      *
@@ -1104,6 +1156,61 @@ declare class VaultFile {
      * ```
      */
     createChildFromStream(params: Omit<Parameters<typeof VaultFile.fromStream>[0], 'config' | 'parentId'>, options?: Parameters<typeof VaultFile.fromStream>[1]): Promise<VaultFile>;
+    /**
+     * Updates the metadata of this file in the vault.
+     *
+     * This method allows you to modify specific metadata properties of the file, such as renaming it.
+     * The instance's metadata property is automatically updated with the response from the server.
+     * Only the provided parameters will be updated; all other metadata remains unchanged.
+     *
+     * @param params - The metadata properties to update
+     * @param params.name - The new name to assign to the file
+     * @param options - Additional options for the request
+     * @param options.signal - AbortSignal to cancel the request
+     *
+     * @returns A Promise that resolves when the update completes successfully
+     * @throws {Error} If the file ID is not set
+     * @throws {FetchError} If the update request fails
+     *
+     * @example
+     * ```ts
+     * // Rename a file
+     * const vaultFile = await VaultFile.fromVaultReference({
+     *     reference: 'vault://file-id',
+     *     config: { vaultUrl, authStrategy }
+     * })
+     * await vaultFile.updateMetadata({ name: 'new-name.txt' })
+     * console.log('File renamed to:', vaultFile.metadata?.originalFileName)
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Rename a file with abort signal
+     * const controller = new AbortController()
+     * await vaultFile.updateMetadata(
+     *     { name: 'document-v2.pdf' },
+     *     { signal: controller.signal }
+     * )
+     * // Later: controller.abort()
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Rename after upload
+     * const file = new File(['content'], 'temp.txt')
+     * const vaultFile = await VaultFile.fromContent({
+     *     name: 'temp.txt',
+     *     content: file,
+     *     config: { vaultUrl, authStrategy },
+     *     upload: true
+     * })
+     * // Later, rename the file
+     * await vaultFile.updateMetadata({ name: 'final-document.txt' })
+     * ```
+     */
+    updateMetadata(params: VaultFileUpdateMetadataParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
 }
 
 /**
@@ -1115,19 +1222,41 @@ declare class VaultFile {
  */
 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
+ * Checks if a URL is a valid vault reference
+ * @param url - The URL to check
+ * @returns true if the URL is a valid vault reference, false otherwise
+ */
+declare function isVaultReference(url: string): boolean;
+/**
+ * Checks if a URL seems like a valid presigned S3 URL, with no additional checks.
+ *
+ * For usage with legacy URLs only. For new URLs, use {@link isTaggedVaultPresignedUrl} instead,
+ * since this function only checks if the URL is a valid S3 URL, not if it was generated by Vault.
+ *
+ * @param url - The URL to check
+ * @returns true if the URL is a valid S3 URL, false otherwise
  */
-declare function isVaultFileS3Url(url: string): boolean;
+declare function isPresignedS3Url(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
+ * Extracts the vault file ID from an S3 presigned URL.
+ * Supports multiple URL formats: tagged vault URLs, vault references, and legacy URL formats.
+ *
+ * @param url - The S3 URL to extract the vault file ID from
+ * @returns The vault file ID (UUID or SHA-256 hash) if extraction succeeds, null otherwise
+ * @example
+ * // Tagged vault URL
+ * extractVaultFileIdFromS3Url('https://vault-prod.s3.amazonaws.com/file?vault-file-id=abc123...')
+ * // Returns: 'abc123...'
+ *
+ * // Vault reference
+ * extractVaultFileIdFromS3Url('vault://2fce5740-83da-49fe-3f10-b32205893ec0')
+ * // Returns: '2fce5740-83da-49fe-3f10-b32205893ec0'
  */
 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
@@ -1135,6 +1264,33 @@ declare function extractVaultFileIdFromS3Url(url: string): string | null;
  * // Returns: 'vault://2fce574083da49fe3f10b32205893ec0bb024fe1c7673fa54927fdfe1d0db9d6'
  */
 declare function convertS3UrlToVaultReference(url: string): string | null;
+/**
+ * Checks if a URL is a tagged vault presigned S3 URL.
+ * Tagged URLs contain vault-specific query parameters (vault-workspace-id, vault-file-id)
+ * that identify the vault workspace and file.
+ *
+ * @param url - The URL to check
+ * @returns true if the URL is a tagged vault presigned URL with valid workspace and file IDs, false otherwise
+ * @example
+ * const isTagged = isTaggedVaultPresignedUrl('https://vault-prod.s3.amazonaws.com/file?vault-workspace-id=abc-123&vault-file-id=def456...')
+ * // Returns: true
+ */
+declare function isTaggedVaultPresignedUrl(url: string): boolean;
+/**
+ * Extracts vault-specific parameters from a tagged vault presigned S3 URL.
+ * Returns workspace ID, file ID, and optional parent ID from the URL query parameters.
+ *
+ * @param url - The tagged vault S3 URL to parse
+ * @returns An object containing fileId, workspaceId, and parentId (if present), or null if the URL is not a tagged vault URL
+ * @example
+ * const params = getVaultParamsFromS3Url('https://vault-prod.s3.amazonaws.com/file?vault-workspace-id=abc-123&vault-file-id=def456&vault-parent-id=parent789')
+ * // Returns: { fileId: 'def456', workspaceId: 'abc-123', parentId: 'parent789' }
+ */
+declare function getVaultParamsFromS3Url(url: string): {
+    fileId: string | null;
+    workspaceId: string | null;
+    parentId: string | null;
+} | null;
 
 declare function vaultClient(vaultConfig: VaultConfig): {
     createFromContent: {
@@ -1165,7 +1321,18 @@ declare function vaultClient(vaultConfig: VaultConfig): {
         signal?: AbortSignal;
         parentId?: string;
     }) => Promise<VaultFile>;
+    createFromContentBulk: (files: Array<{
+        content: Blob | File;
+        name?: string;
+        mimeType?: string;
+        parentId?: string;
+        onMissingParent?: "error" | "create-as-root";
+        onParentConflict?: "error" | "update-parent-id" | "ignore";
+    }>, options?: {
+        upload?: boolean;
+        signal?: AbortSignal;
+    }) => Promise<VaultFile[]>;
 };
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, isS3UrlExpired, isVaultFileS3Url, vaultClient };
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, getVaultParamsFromS3Url, isS3UrlExpired, isTaggedVaultPresignedUrl, isPresignedS3Url as isVaultFileS3Url, isVaultReference, vaultClient };
 export type { AuthStrategy, VaultConfig };

package/dist/index.d.mts

@@ -88,6 +88,22 @@ type VaultFileParams = {
     config: VaultConfig;
 };
 type OnMissingParent = 'error' | 'create-as-root';
+type OnParentConflict = 'error' | 'update-parent-id' | 'ignore';
+/**
+ * Parameters for updating metadata of a VaultFile.
+ */
+interface VaultFileUpdateMetadataParams {
+    /** The new name to assign to the file. If not provided, the name will not be changed. */
+    name?: string;
+}
+type BulkFileInput = {
+    content: Blob | File;
+    name?: string;
+    mimeType?: string;
+    parentId?: string;
+    onMissingParent?: OnMissingParent;
+    onParentConflict?: OnParentConflict;
+};
 /**
  * Represents a file in the vault and allows interacting with it.
  *
@@ -154,6 +170,7 @@ declare class VaultFile {
      * @param metadata.mimeType - The mime type of the file
      * @param metadata.parentId - The ID of the parent file for hierarchical file relationships
      * @param metadata.onMissingParent - What to do if the parent file does not exist or has been deleted
+     * @param metadata.onParentConflict - What to do if the file already exists as an active child of another file
      * @param options - The options for the request
      * @param options.signal - The signal to abort the request
      *
@@ -219,6 +236,7 @@ declare class VaultFile {
      * @param params.upload - Whether to upload the file (default: false)
      * @param params.parentId - The ID of the parent file for hierarchical file relationships
      * @param params.onMissingParent - What to do if the parent file does not exist or has been deleted
+     * @param params.onParentConflict - What to do if the file already exists as an active child of another file
      * @param options - The options for the request
      * @param options.signal - The signal to abort the request
      *
@@ -278,6 +296,7 @@ declare class VaultFile {
         upload?: boolean;
         parentId?: string;
         onMissingParent?: OnMissingParent;
+        onParentConflict?: OnParentConflict;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
@@ -292,6 +311,7 @@ declare class VaultFile {
      * @param params.contentType - The MIME type of the content (optional)
      * @param params.parentId - The ID of the parent file for hierarchical file relationships
      * @param params.onMissingParent - What to do if the parent file does not exist or has been deleted
+     * @param params.onParentConflict - What to do if the file already exists as an active child of another file
      * @param options - The options for the request
      * @param options.signal - The signal to abort the request
      *
@@ -334,9 +354,41 @@ declare class VaultFile {
         contentType?: string;
         parentId?: string;
         onMissingParent?: OnMissingParent;
+        onParentConflict?: OnParentConflict;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<VaultFile>;
+    /**
+     * Creates multiple VaultFile instances from given content in a single request.
+     *
+     * @param params - Parameters for creating VaultFiles from content
+     * @param params.files - Array of file inputs with content and optional metadata
+     * @param params.config - The configuration for the VaultFiles
+     * @param params.upload - Whether to upload all files (default: false)
+     * @param options - The options for the request
+     * @param options.signal - The signal to abort the request
+     *
+     * @returns Array of new VaultFile instances
+     *
+     * @example
+     * ```ts
+     * const files = await VaultFile.fromContentBulk({
+     *     files: [
+     *         { content: blob1, name: 'file1.txt' },
+     *         { content: blob2, name: 'file2.txt', parentId: 'parent-id' },
+     *     ],
+     *     config: { vaultUrl, authStrategy },
+     *     upload: true
+     * })
+     * ```
+     */
+    static fromContentBulk(params: {
+        files: BulkFileInput[];
+        config: VaultConfig;
+        upload?: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<VaultFile[]>;
     /**
      * Fetches and populates the metadata fields for this VaultFile instance.
      *
@@ -1104,6 +1156,61 @@ declare class VaultFile {
      * ```
      */
     createChildFromStream(params: Omit<Parameters<typeof VaultFile.fromStream>[0], 'config' | 'parentId'>, options?: Parameters<typeof VaultFile.fromStream>[1]): Promise<VaultFile>;
+    /**
+     * Updates the metadata of this file in the vault.
+     *
+     * This method allows you to modify specific metadata properties of the file, such as renaming it.
+     * The instance's metadata property is automatically updated with the response from the server.
+     * Only the provided parameters will be updated; all other metadata remains unchanged.
+     *
+     * @param params - The metadata properties to update
+     * @param params.name - The new name to assign to the file
+     * @param options - Additional options for the request
+     * @param options.signal - AbortSignal to cancel the request
+     *
+     * @returns A Promise that resolves when the update completes successfully
+     * @throws {Error} If the file ID is not set
+     * @throws {FetchError} If the update request fails
+     *
+     * @example
+     * ```ts
+     * // Rename a file
+     * const vaultFile = await VaultFile.fromVaultReference({
+     *     reference: 'vault://file-id',
+     *     config: { vaultUrl, authStrategy }
+     * })
+     * await vaultFile.updateMetadata({ name: 'new-name.txt' })
+     * console.log('File renamed to:', vaultFile.metadata?.originalFileName)
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Rename a file with abort signal
+     * const controller = new AbortController()
+     * await vaultFile.updateMetadata(
+     *     { name: 'document-v2.pdf' },
+     *     { signal: controller.signal }
+     * )
+     * // Later: controller.abort()
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Rename after upload
+     * const file = new File(['content'], 'temp.txt')
+     * const vaultFile = await VaultFile.fromContent({
+     *     name: 'temp.txt',
+     *     content: file,
+     *     config: { vaultUrl, authStrategy },
+     *     upload: true
+     * })
+     * // Later, rename the file
+     * await vaultFile.updateMetadata({ name: 'final-document.txt' })
+     * ```
+     */
+    updateMetadata(params: VaultFileUpdateMetadataParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
 }
 
 /**
@@ -1115,19 +1222,41 @@ declare class VaultFile {
  */
 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
+ * Checks if a URL is a valid vault reference
+ * @param url - The URL to check
+ * @returns true if the URL is a valid vault reference, false otherwise
+ */
+declare function isVaultReference(url: string): boolean;
+/**
+ * Checks if a URL seems like a valid presigned S3 URL, with no additional checks.
+ *
+ * For usage with legacy URLs only. For new URLs, use {@link isTaggedVaultPresignedUrl} instead,
+ * since this function only checks if the URL is a valid S3 URL, not if it was generated by Vault.
+ *
+ * @param url - The URL to check
+ * @returns true if the URL is a valid S3 URL, false otherwise
  */
-declare function isVaultFileS3Url(url: string): boolean;
+declare function isPresignedS3Url(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
+ * Extracts the vault file ID from an S3 presigned URL.
+ * Supports multiple URL formats: tagged vault URLs, vault references, and legacy URL formats.
+ *
+ * @param url - The S3 URL to extract the vault file ID from
+ * @returns The vault file ID (UUID or SHA-256 hash) if extraction succeeds, null otherwise
+ * @example
+ * // Tagged vault URL
+ * extractVaultFileIdFromS3Url('https://vault-prod.s3.amazonaws.com/file?vault-file-id=abc123...')
+ * // Returns: 'abc123...'
+ *
+ * // Vault reference
+ * extractVaultFileIdFromS3Url('vault://2fce5740-83da-49fe-3f10-b32205893ec0')
+ * // Returns: '2fce5740-83da-49fe-3f10-b32205893ec0'
  */
 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
@@ -1135,6 +1264,33 @@ declare function extractVaultFileIdFromS3Url(url: string): string | null;
  * // Returns: 'vault://2fce574083da49fe3f10b32205893ec0bb024fe1c7673fa54927fdfe1d0db9d6'
  */
 declare function convertS3UrlToVaultReference(url: string): string | null;
+/**
+ * Checks if a URL is a tagged vault presigned S3 URL.
+ * Tagged URLs contain vault-specific query parameters (vault-workspace-id, vault-file-id)
+ * that identify the vault workspace and file.
+ *
+ * @param url - The URL to check
+ * @returns true if the URL is a tagged vault presigned URL with valid workspace and file IDs, false otherwise
+ * @example
+ * const isTagged = isTaggedVaultPresignedUrl('https://vault-prod.s3.amazonaws.com/file?vault-workspace-id=abc-123&vault-file-id=def456...')
+ * // Returns: true
+ */
+declare function isTaggedVaultPresignedUrl(url: string): boolean;
+/**
+ * Extracts vault-specific parameters from a tagged vault presigned S3 URL.
+ * Returns workspace ID, file ID, and optional parent ID from the URL query parameters.
+ *
+ * @param url - The tagged vault S3 URL to parse
+ * @returns An object containing fileId, workspaceId, and parentId (if present), or null if the URL is not a tagged vault URL
+ * @example
+ * const params = getVaultParamsFromS3Url('https://vault-prod.s3.amazonaws.com/file?vault-workspace-id=abc-123&vault-file-id=def456&vault-parent-id=parent789')
+ * // Returns: { fileId: 'def456', workspaceId: 'abc-123', parentId: 'parent789' }
+ */
+declare function getVaultParamsFromS3Url(url: string): {
+    fileId: string | null;
+    workspaceId: string | null;
+    parentId: string | null;
+} | null;
 
 declare function vaultClient(vaultConfig: VaultConfig): {
     createFromContent: {
@@ -1165,7 +1321,18 @@ declare function vaultClient(vaultConfig: VaultConfig): {
         signal?: AbortSignal;
         parentId?: string;
     }) => Promise<VaultFile>;
+    createFromContentBulk: (files: Array<{
+        content: Blob | File;
+        name?: string;
+        mimeType?: string;
+        parentId?: string;
+        onMissingParent?: "error" | "create-as-root";
+        onParentConflict?: "error" | "update-parent-id" | "ignore";
+    }>, options?: {
+        upload?: boolean;
+        signal?: AbortSignal;
+    }) => Promise<VaultFile[]>;
 };
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, isS3UrlExpired, isVaultFileS3Url, vaultClient };
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, convertS3UrlToVaultReference, extractVaultFileIdFromS3Url, getVaultParamsFromS3Url, isS3UrlExpired, isTaggedVaultPresignedUrl, isPresignedS3Url as isVaultFileS3Url, isVaultReference, vaultClient };
 export type { AuthStrategy, VaultConfig };