@meistrari/vault-sdk 0.0.12 → 1.0.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { FileMetadata } from '@meistrari/vault-shared/schemas';
+
 interface AuthStrategy {
     getHeaders: () => Headers;
 }
@@ -12,76 +14,251 @@ declare class APIKeyAuthStrategy implements AuthStrategy {
     constructor(apiKey: string);
 }
 
-type FetchParams = {
-    method: 'GET' | 'POST' | 'PUT';
-    path: string;
-    body?: any;
-    ignoreHeaders?: boolean;
-};
-type VaultParams = {
-    name: string;
-    authStrategy: AuthStrategy;
+type VaultConfig = {
     vaultUrl: string;
+    authStrategy: AuthStrategy;
 };
+type VaultFileParams = {
+    id?: string;
+    name?: string;
+    content?: Blob;
+    metadata?: FileMetadata | null;
+    config: VaultConfig;
+};
+/**
+ * Represents a file in the vault and allows interacting with it.
+ *
+ * @example
+ * ```ts
+ * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', {
+ *     vaultUrl,
+ *     authStrategy,
+ * })
+ * ```
+ */
 declare class VaultFile {
-    readonly vaultUrl: string;
-    name: string;
-    headers: Headers;
-    constructor(params: VaultParams);
-    getVaultUrl(): string;
-    removeVaultPrefix(url: string): string;
-    getUploadUrl(): Promise<URL>;
-    getDownloadUrl(): Promise<URL>;
-    refreshAuth(authStrategy: AuthStrategy): void;
-    _fetch(params: FetchParams): Promise<any>;
+    id: string | undefined;
+    name: string | undefined;
+    metadata: FileMetadata | undefined | null;
+    config: VaultConfig;
+    content: Blob | undefined;
+    lastDownloadUrl: {
+        url: URL;
+        expiresAt: Date;
+    } | undefined;
+    lastUploadUrl: {
+        url: URL;
+        expiresAt: Date;
+    } | undefined;
+    /**
+     * 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.
+     *
+     * @param params - The parameters for the VaultFile constructor
+     * @param params.config - The configuration for the VaultFile
+     * @param params.content - The content of the file
+     * @param params.id - The ID of the file
+     * @param params.name - The name of the file
+     * @param params.metadata - The metadata of the file
+     */
+    constructor({ config, content, id, name, metadata }: VaultFileParams);
+    /**
+     * Gets the headers for the request based on the auth strategy.
+     *
+     * @returns The headers for the request
+     */
+    private get headers();
+    /**
+     * Performs a request to the vault service and handles the response or errors.
+     *
+     * @param params - The parameters for the fetch
+     * @param params.method - The method to use for the fetch
+     * @param params.path - The path to fetch
+     * @param params.body - The body of the request
+     * @returns The response from the vault
+     * @throws {FetchError} If the fetch fails
+     */
+    private _fetch;
+    /**
+     * Creates a new file in the vault.
+     *
+     * @returns The metadata of the file
+     * @throws {Error} If the file ID is not set
+     * @throws {FetchError} If the metadata fetch fails
+     */
+    private _createFile;
+    /**
+     * Creates a new VaultFile instance from a vault reference.
+     *
+     * @param params - The parameters for creating a VaultFile from a vault reference
+     * @param params.reference - The reference to the file in the vault
+     * @param params.config - The configuration for the VaultFile
+     * @param params.download - Whether to download the file content (default: false)
+     * @returns A new VaultFile instance
+     *
+     * @example
+     * ```ts
+     * // Lazily download the file content
+     * const vaultFile = await VaultFile.fromVaultReference({
+     *     reference: 'vault://1234567890',
+     *     config: {
+     *         vaultUrl,
+     *         authStrategy,
+     *     }
+     * })
+     * const content = await vaultFile.download()
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Download the file content while creating the instance
+     * const vaultFile = await VaultFile.fromVaultReference({
+     *     reference: 'vault://1234567890',
+     *     config: {
+     *         vaultUrl,
+     *         authStrategy,
+     *     },
+     *     download: true
+     * })
+     * const content = vaultFile.content
+     * ```
+     */
+    static fromVaultReference(params: {
+        reference: string;
+        config: VaultConfig;
+        download?: boolean;
+    }): Promise<VaultFile>;
     /**
-     * Adds a SHA-256 hash of the file content as a prefix to the filename. This ensures uniqueness and prevents
-     * files with identical names but different content from overwriting each other in the vault.
+     * Creates a new VaultFile instance from given content.
      *
-     * The resulting filename format is: "{hash}-{originalName}"
+     * @param params - The parameters for creating a VaultFile from content
+     * @param params.name - The name of the file
+     * @param params.content - The content of the file
+     * @param params.config - The configuration for the VaultFile
+     * @param params.upload - Whether to upload the file (default: false)
+     * @returns A new VaultFile instance
      *
-     * IMPORTANT: The modified filename must be stored and used for all future operations with this file in the vault,
-     * as it becomes the file's unique identifier. The original filename alone will not be sufficient to retrieve
-     * the file later.
+     * @example
+     * ```ts
+     * // Lazily upload the file content
+     * const file = new File(['content'], 'document.txt')
+     * const vaultFile = await VaultFile.fromContent({
+     *     name: 'document.txt',
+     *     content: file,
+     *     config: {
+     *         vaultUrl,
+     *         authStrategy,
+     *     }
+     * })
+     * await vaultFile.upload()
+     * ```
      *
      * @example
+     * ```ts
+     * // Upload the file content while creating the instance
      * const file = new File(['content'], 'document.txt')
-     * await vaultFile.addHashToName(file)
-     * // vaultFile.name becomes: "a1b2c3...xyz-document.txt"
+     * const vaultFile = await VaultFile.fromContent({
+     *     name: 'document.txt',
+     *     content: file,
+     *     config: {
+     *         vaultUrl,
+     *         authStrategy,
+     *     },
+     *     upload: true
+     * })
+     * ```
+     */
+    static fromContent(params: {
+        name: string;
+        content: Blob | File;
+        config: VaultConfig;
+        upload?: boolean;
+    }): Promise<VaultFile>;
+    /**
+     * Populates the metadata of the file instance.
      *
-     * @param file - The file to generate a hash for
-     * @returns The new filename with the hash prefix
+     * @returns The file instance
+     * @throws {Error} If the file ID is not set
+     * @throws {FetchError} If the metadata fetch fails
      */
-    addHashToName(file: Blob): Promise<string>;
+    populateMetadata(): Promise<this | undefined>;
     /**
-     * Uploads a file to the vault.
+     * Gets the vault reference for this file.
      *
-     * Files are saved with the given file names, so files with the same name within the same workspace
-     * will overwrite each other. To prevent accidental overwrites and support multiple files with the
-     * same original name, you should call addHashToName() before uploading to add a unique content-based
-     * hash to the filename.
+     * @returns The vault reference in the format `vault://{fileId}`
+     * @throws {Error} If the file ID is not set
+     */
+    getVaultReference(): string;
+    /**
+     * Fetches the metadata of the file.
+     *
+     * @returns The metadata of the file
+     * @throws {Error} If the file ID is not set
+     * @throws {FetchError} If the metadata fetch fails
+     */
+    getFileMetadata(): Promise<FileMetadata>;
+    /**
+     * Fetches a upload URL for the file.
+     *
+     * @returns The upload URL for the file
+     * @throws {Error} If the vault service returns an invalid response
+     * @throws {FetchError} If the upload URL fetch fails
+     */
+    getUploadUrl(): Promise<URL>;
+    /**
+     * Fetches a download URL for the file.
+     *
+     * @returns The download URL for the file
+     * @throws {Error} If the vault service returns an invalid response
+     * @throws {Error} If not file ID, name or content is set
+     * @throws {FetchError} If the download URL fetch fails
+     */
+    getDownloadUrl(): Promise<URL>;
+    /**
+     * Uploads a file to the vault.
      *
      * @example
+     * ```ts
      * const file = new File(['content'], 'document.txt')
-     * await vaultFile.addHashToName(file) // Adds hash prefix to filename
+     * const vaultFile = await VaultFile.fromBlob('document.txt', file, { vaultUrl, authStrategy })
      * await vaultFile.upload(file)
+     * ```
      *
-     * @param file - The file to upload to the vault
+     * @param file - The file to upload to the vault. If not provided, the file content will be taken from the `content` property.
      * @throws {FetchError} If the upload fails
+     * @throws {Error} If the file content is not set and no file is provided
      * @returns Promise that resolves when upload is complete
      */
-    upload(file: Blob): Promise<void>;
+    upload(file?: Blob, url?: string): Promise<void>;
+    /**
+     * Downloads a file from the vault.
+     *
+     * @param responseType - The type of the response
+     * @returns The response from the vault
+     *
+     * @example
+     * ```ts
+     * const vaultFile = await VaultFile.fromVaultReference('vault://1234567890', { vaultUrl, authStrategy })
+     * const content = await vaultFile.download()
+     * ```
+     */
     download(responseType?: 'blob'): Promise<Blob>;
     download(responseType: 'base64'): Promise<string>;
 }
 
 declare class FetchError extends Error {
+    readonly message: string;
+    readonly url: string;
+    readonly method: string;
     readonly response: Response;
-    constructor(message: string, response: Response);
+    constructor(message: string, url: string, method: string, response: Response);
+    static from(url: string, method: string, response: Response): Promise<FetchError>;
 }
 
-declare function useVault(vaultUrl: string, authStrategy: AuthStrategy): {
-    createVaultFile: (name: string) => VaultFile;
+declare function vaultClient(config: VaultConfig): {
+    createFromContent: (name: string, content: Blob | File) => Promise<VaultFile>;
+    createFromReference: (reference: string) => Promise<VaultFile>;
 };
 
-export { APIKeyAuthStrategy, type AuthStrategy, DataTokenAuthStrategy, FetchError, VaultFile, useVault };
+export { APIKeyAuthStrategy, type AuthStrategy, DataTokenAuthStrategy, FetchError, type VaultConfig, VaultFile, vaultClient };