@meistrari/vault-sdk 1.4.3 → 1.6.0

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,9 +197,92 @@ 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.6.0";
+const license = "UNLICENSED";
+const repository = {
+	type: "git",
+	url: "https://github.com/meistrari/vault.git"
+};
+const exports$1 = {
+	".": {
+		types: "./dist/index.d.ts",
+		"import": "./dist/index.mjs",
+		require: "./dist/index.cjs"
+	}
+};
+const main = "dist/index.mjs";
+const types = "dist/index.d.ts";
+const files = [
+	"dist"
+];
+const scripts = {
+	test: "vitest --no-watch",
+	"test:watch": "vitest",
+	build: "unbuild",
+	lint: "eslint .",
+	"lint:fix": "eslint . --fix",
+	check: "bun run lint && bun tsc --noEmit"
+};
+const dependencies = {
+	"@meistrari/vault-shared": "workspace:*",
+	"file-type": "21.0.0",
+	"mime-types": "3.0.1",
+	ofetch: "1.4.1",
+	zod: "3.23.8"
+};
+const devDependencies = {
+	"@types/bun": "latest",
+	"@types/mime-types": "3.0.1",
+	msw: "2.6.8",
+	unbuild: "2.0.0",
+	vitest: "2.1.9"
+};
+const peerDependencies = {
+	typescript: "^5.0.0"
+};
+const publishConfig = {
+	access: "public"
+};
+const packageJson = {
+	name: name,
+	version: version,
+	license: license,
+	repository: repository,
+	exports: exports$1,
+	main: main,
+	types: types,
+	files: files,
+	scripts: scripts,
+	dependencies: dependencies,
+	devDependencies: devDependencies,
+	peerDependencies: peerDependencies,
+	publishConfig: publishConfig
+};
+
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => {
@@ -210,8 +293,23 @@ 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) {
     throw await FetchError.from(request.url, request.method, response);
@@ -220,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
@@ -253,7 +353,9 @@ class VaultFile {
    * @returns The headers for the request
    */
   get headers() {
-    return this.config.authStrategy.getHeaders();
+    const headers = this.config.authStrategy.getHeaders();
+    headers.set("User-Agent", `vault-js-sdk:${packageJson.version}`);
+    return headers;
   }
   /**
    * Performs a request to the vault service and handles the response or errors.
@@ -276,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;
     }
@@ -454,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
@@ -621,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
@@ -679,6 +911,79 @@ class VaultFile {
   }
 }
 
+function isS3UrlExpired(url) {
+  try {
+    const urlObj = new URL(url);
+    const amzDate = urlObj.searchParams.get("X-Amz-Date");
+    const amzExpires = urlObj.searchParams.get("X-Amz-Expires");
+    if (!amzDate || !amzExpires)
+      return false;
+    const year = Number.parseInt(amzDate.substring(0, 4));
+    const month = Number.parseInt(amzDate.substring(4, 6)) - 1;
+    const day = Number.parseInt(amzDate.substring(6, 8));
+    const hours = Number.parseInt(amzDate.substring(9, 11));
+    const minutes = Number.parseInt(amzDate.substring(11, 13));
+    const seconds = Number.parseInt(amzDate.substring(13, 15));
+    const signedDate = new Date(Date.UTC(year, month, day, hours, minutes, seconds));
+    const expiresInSeconds = Number.parseInt(amzExpires);
+    const expirationTime = signedDate.getTime() + expiresInSeconds * 1e3;
+    const currentTime = Date.now();
+    return currentTime > expirationTime;
+  } catch {
+    return false;
+  }
+}
+function isVaultReference(url) {
+  return url.startsWith("vault://") && url.length === 10;
+}
+function isVaultFileS3Url(url) {
+  const urlObj = new URL(url);
+  const amzDate = urlObj.searchParams.get("X-Amz-Date");
+  const amzExpires = urlObj.searchParams.get("X-Amz-Expires");
+  return urlObj.hostname.includes("amazonaws.com") && Boolean(amzDate) && Boolean(amzExpires);
+}
+const URL_STRATEGIES = [
+  {
+    separator: "/",
+    extractSegments: ([workspaceId, vaultFileId]) => ({
+      workspaceId,
+      vaultFileId
+    })
+  },
+  {
+    separator: "_",
+    extractSegments: ([vaultFileId, workspaceId]) => ({
+      vaultFileId,
+      workspaceId
+    })
+  }
+];
+function extractVaultFileIdFromS3Url(url) {
+  if (isVaultReference(url))
+    return url.replace("vault://", "");
+  try {
+    if (!isVaultFileS3Url(url))
+      return null;
+    const urlObj = new URL(url);
+    const strategy = URL_STRATEGIES.find((strategy2) => urlObj.pathname.includes(strategy2.separator));
+    if (!strategy)
+      return null;
+    const segments = urlObj.pathname.split(strategy.separator).filter((segment) => segment.length > 0);
+    if (segments.length < 2)
+      return null;
+    const extractedIds = strategy.extractSegments(segments);
+    if (!extractedIds || !extractedIds.vaultFileId || !extractedIds.workspaceId || extractedIds.vaultFileId.length < 32)
+      return null;
+    return extractedIds.vaultFileId;
+  } catch {
+    return null;
+  }
+}
+function convertS3UrlToVaultReference(url) {
+  const vaultFileId = extractVaultFileIdFromS3Url(url);
+  return vaultFileId ? `vault://${vaultFileId}` : null;
+}
+
 function vaultClient(vaultConfig) {
   const config = resolveConfig(vaultConfig);
   function createFromContent(name, content, options) {
@@ -694,11 +999,23 @@ 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;
 exports.DataTokenAuthStrategy = DataTokenAuthStrategy;
 exports.FetchError = FetchError;
 exports.VaultFile = VaultFile;
+exports.convertS3UrlToVaultReference = convertS3UrlToVaultReference;
+exports.extractVaultFileIdFromS3Url = extractVaultFileIdFromS3Url;
+exports.isS3UrlExpired = isS3UrlExpired;
+exports.isVaultFileS3Url = isVaultFileS3Url;
 exports.vaultClient = vaultClient;

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
@@ -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 };