@net-protocol/storage 0.1.3 → 0.1.5

package/README.md

@@ -224,6 +224,9 @@ import {
   assembleChunks,
   parseNetReferences,
   processDataForStorage,
+  fileToDataUri,
+  detectFileTypeFromBase64,
+  base64ToDataUri,
 } from "@net-protocol/storage";
 
 // Generate storage key bytes
@@ -242,6 +245,32 @@ const references = parseNetReferences('<net k="hash" v="0.0.1" />');
 const result = processDataForStorage(data, operatorAddress);
 ```
 
+### File Utilities
+
+```typescript
+import {
+  fileToDataUri,
+  detectFileTypeFromBase64,
+  base64ToDataUri,
+} from "@net-protocol/storage";
+
+// Convert File/Blob to data URI (browser-only)
+// Note: fileToDataUri requires browser APIs (FileReader) and should only be used in browser environments
+const file = event.target.files[0];
+const dataUri = await fileToDataUri(file);
+// Returns: "data:application/pdf;base64,JVBERi0xLjQK..."
+
+// Detect file type from raw base64 data (works in both browser and Node.js)
+const base64Data = "JVBERi0xLjQK..."; // Raw base64 without prefix
+const mimeType = detectFileTypeFromBase64(base64Data);
+// Returns: "application/pdf"
+
+// Convert raw base64 to data URI with automatic type detection (works in both browser and Node.js)
+const dataUri = base64ToDataUri(base64Data);
+// Returns: "data:application/pdf;base64,JVBERi0xLjQK..."
+// Falls back to "application/octet-stream" if type cannot be detected
+```
+
 ## API Reference
 
 ### React Hooks

package/dist/index.d.mts

@@ -484,6 +484,56 @@ declare function processDataForStorage(data: string, operatorAddress: string, st
     error?: string;
 };
 
+/**
+ * File utilities for converting files to data URIs and detecting file types from base64 data.
+ */
+/**
+ * Converts a File or Blob to a data URI string.
+ * Uses FileReader API to read the file and returns the full data URI including prefix.
+ *
+ * @param file - The File or Blob object to convert
+ * @returns Promise that resolves to a data URI string (e.g., "data:application/pdf;base64,...")
+ * @throws Error if FileReader fails to read the file
+ *
+ * @example
+ * ```typescript
+ * const file = event.target.files[0];
+ * const dataUri = await fileToDataUri(file);
+ * // Returns: "data:application/pdf;base64,JVBERi0xLjQK..."
+ * ```
+ */
+declare function fileToDataUri(file: File | Blob): Promise<string>;
+/**
+ * Detects the MIME type from raw base64 data by checking magic bytes (file signatures).
+ * Supports common file types: PDF, PNG, JPEG, GIF, WebP, SVG, HTML, MP3, MP4, ZIP, JSON.
+ *
+ * @param base64Data - Raw base64 string (without data URI prefix)
+ * @returns MIME type string (e.g., "application/pdf") or undefined if type cannot be detected
+ *
+ * @example
+ * ```typescript
+ * const base64Data = "JVBERi0xLjQK..."; // Raw PDF base64
+ * const mimeType = detectFileTypeFromBase64(base64Data);
+ * // Returns: "application/pdf"
+ * ```
+ */
+declare function detectFileTypeFromBase64(base64Data: string): string | undefined;
+/**
+ * Converts raw base64 data to a data URI by detecting the file type and adding the appropriate prefix.
+ * Falls back to "application/octet-stream" if the file type cannot be detected.
+ *
+ * @param base64Data - Raw base64 string (without data URI prefix)
+ * @returns Complete data URI string (e.g., "data:application/pdf;base64,...")
+ *
+ * @example
+ * ```typescript
+ * const base64Data = "JVBERi0xLjQK..."; // Raw PDF base64
+ * const dataUri = base64ToDataUri(base64Data);
+ * // Returns: "data:application/pdf;base64,JVBERi0xLjQK..."
+ * ```
+ */
+declare function base64ToDataUri(base64Data: string): string;
+
 declare const STORAGE_CONTRACT: {
     abi: Abi;
     address: `0x${string}`;
@@ -519,4 +569,4 @@ declare const CONCURRENT_XML_FETCHES = 3;
  */
 declare function resolveXmlRecursive(content: string, defaultOperator: string, client: PublicClient, maxDepth: number, visited?: Set<string>, inheritedOperator?: string): Promise<string>;
 
-export { type BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, type ChunkedMetadata, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, type StorageClientOptions, type StorageData, type UseStorageOptions, type UseXmlStorageOptions, type XmlReference$1 as XmlReference, assembleChunks, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectStorageType, encodeStorageKeyForUrl, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, parseNetReferences, processDataForStorage, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, useBulkStorage, useStorage, useStorageForOperator, useStorageForOperatorAndKey, useStorageFromRouter, useStorageTotalWrites, useXmlStorage, validateDataSize };
+export { type BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, type ChunkedMetadata, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, type StorageClientOptions, type StorageData, type UseStorageOptions, type UseXmlStorageOptions, type XmlReference$1 as XmlReference, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, parseNetReferences, processDataForStorage, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, useBulkStorage, useStorage, useStorageForOperator, useStorageForOperatorAndKey, useStorageFromRouter, useStorageTotalWrites, useXmlStorage, validateDataSize };

package/dist/index.d.ts

@@ -484,6 +484,56 @@ declare function processDataForStorage(data: string, operatorAddress: string, st
     error?: string;
 };
 
+/**
+ * File utilities for converting files to data URIs and detecting file types from base64 data.
+ */
+/**
+ * Converts a File or Blob to a data URI string.
+ * Uses FileReader API to read the file and returns the full data URI including prefix.
+ *
+ * @param file - The File or Blob object to convert
+ * @returns Promise that resolves to a data URI string (e.g., "data:application/pdf;base64,...")
+ * @throws Error if FileReader fails to read the file
+ *
+ * @example
+ * ```typescript
+ * const file = event.target.files[0];
+ * const dataUri = await fileToDataUri(file);
+ * // Returns: "data:application/pdf;base64,JVBERi0xLjQK..."
+ * ```
+ */
+declare function fileToDataUri(file: File | Blob): Promise<string>;
+/**
+ * Detects the MIME type from raw base64 data by checking magic bytes (file signatures).
+ * Supports common file types: PDF, PNG, JPEG, GIF, WebP, SVG, HTML, MP3, MP4, ZIP, JSON.
+ *
+ * @param base64Data - Raw base64 string (without data URI prefix)
+ * @returns MIME type string (e.g., "application/pdf") or undefined if type cannot be detected
+ *
+ * @example
+ * ```typescript
+ * const base64Data = "JVBERi0xLjQK..."; // Raw PDF base64
+ * const mimeType = detectFileTypeFromBase64(base64Data);
+ * // Returns: "application/pdf"
+ * ```
+ */
+declare function detectFileTypeFromBase64(base64Data: string): string | undefined;
+/**
+ * Converts raw base64 data to a data URI by detecting the file type and adding the appropriate prefix.
+ * Falls back to "application/octet-stream" if the file type cannot be detected.
+ *
+ * @param base64Data - Raw base64 string (without data URI prefix)
+ * @returns Complete data URI string (e.g., "data:application/pdf;base64,...")
+ *
+ * @example
+ * ```typescript
+ * const base64Data = "JVBERi0xLjQK..."; // Raw PDF base64
+ * const dataUri = base64ToDataUri(base64Data);
+ * // Returns: "data:application/pdf;base64,JVBERi0xLjQK..."
+ * ```
+ */
+declare function base64ToDataUri(base64Data: string): string;
+
 declare const STORAGE_CONTRACT: {
     abi: Abi;
     address: `0x${string}`;
@@ -519,4 +569,4 @@ declare const CONCURRENT_XML_FETCHES = 3;
  */
 declare function resolveXmlRecursive(content: string, defaultOperator: string, client: PublicClient, maxDepth: number, visited?: Set<string>, inheritedOperator?: string): Promise<string>;
 
-export { type BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, type ChunkedMetadata, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, type StorageClientOptions, type StorageData, type UseStorageOptions, type UseXmlStorageOptions, type XmlReference$1 as XmlReference, assembleChunks, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectStorageType, encodeStorageKeyForUrl, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, parseNetReferences, processDataForStorage, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, useBulkStorage, useStorage, useStorageForOperator, useStorageForOperatorAndKey, useStorageFromRouter, useStorageTotalWrites, useXmlStorage, validateDataSize };
+export { type BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, type ChunkedMetadata, MAX_XML_DEPTH, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, type StorageClientOptions, type StorageData, type UseStorageOptions, type UseXmlStorageOptions, type XmlReference$1 as XmlReference, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, parseNetReferences, processDataForStorage, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, useBulkStorage, useStorage, useStorageForOperator, useStorageForOperatorAndKey, useStorageFromRouter, useStorageTotalWrites, useXmlStorage, validateDataSize };

package/dist/index.js

@@ -2072,6 +2072,110 @@ var StorageClient = class {
   }
 };
 
+// src/utils/fileUtils.ts
+var PDF_MAGIC_BYTES = "JVBERi";
+var PNG_MAGIC_BYTES = "iVBORw0KGgo";
+var JPEG_MAGIC_BYTES = "/9j/";
+var GIF_MAGIC_BYTES = "R0lGODlh";
+var WEBP_MAGIC_BYTES = "UklGRi";
+var ZIP_MAGIC_BYTES = "UEsDB";
+function fileToDataUri(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => {
+      const result = reader.result;
+      if (typeof result === "string") {
+        resolve(result);
+      } else {
+        reject(new Error("FileReader did not return a string result"));
+      }
+    };
+    reader.onerror = () => {
+      reject(new Error("Failed to read file"));
+    };
+    reader.readAsDataURL(file);
+  });
+}
+function detectFileTypeFromBase64(base64Data) {
+  if (!base64Data || base64Data.length === 0) {
+    return void 0;
+  }
+  try {
+    if (base64Data.startsWith(PDF_MAGIC_BYTES)) {
+      return "application/pdf";
+    }
+    if (base64Data.startsWith(PNG_MAGIC_BYTES)) {
+      return "image/png";
+    }
+    if (base64Data.startsWith(JPEG_MAGIC_BYTES)) {
+      return "image/jpeg";
+    }
+    if (base64Data.startsWith(GIF_MAGIC_BYTES)) {
+      return "image/gif";
+    }
+    if (base64Data.startsWith(WEBP_MAGIC_BYTES) && base64Data.length >= 20) {
+      try {
+        const decoded = atob(base64Data.substring(0, 20));
+        if (decoded.includes("WEBP")) {
+          return "image/webp";
+        }
+      } catch {
+      }
+    }
+    if (base64Data.length > 10) {
+      try {
+        const decoded = atob(base64Data.substring(0, Math.min(200, base64Data.length)));
+        if (decoded.includes("<svg") || decoded.includes("<SVG")) {
+          return "image/svg+xml";
+        }
+      } catch {
+      }
+    }
+    if (base64Data.length > 10) {
+      try {
+        const decoded = atob(base64Data.substring(0, Math.min(200, base64Data.length)));
+        const lowerDecoded = decoded.toLowerCase();
+        if (lowerDecoded.includes("<html") || lowerDecoded.includes("<!doctype")) {
+          return "text/html";
+        }
+      } catch {
+      }
+    }
+    if (base64Data.startsWith("SUQz") || base64Data.startsWith("/9s=")) {
+      return "audio/mpeg";
+    }
+    if (base64Data.length > 20) {
+      try {
+        const decoded = atob(base64Data.substring(0, Math.min(50, base64Data.length)));
+        if (decoded.includes("ftyp")) {
+          return "video/mp4";
+        }
+      } catch {
+      }
+    }
+    if (base64Data.startsWith(ZIP_MAGIC_BYTES)) {
+      return "application/zip";
+    }
+    if (base64Data.length > 2) {
+      try {
+        const decoded = atob(base64Data.substring(0, Math.min(10, base64Data.length)));
+        const trimmed = decoded.trim();
+        if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+          return "application/json";
+        }
+      } catch {
+      }
+    }
+    return void 0;
+  } catch (error) {
+    return void 0;
+  }
+}
+function base64ToDataUri(base64Data) {
+  const mimeType = detectFileTypeFromBase64(base64Data) || "application/octet-stream";
+  return `data:${mimeType};base64,${base64Data}`;
+}
+
 exports.CHUNKED_STORAGE_CONTRACT = CHUNKED_STORAGE_CONTRACT;
 exports.CHUNKED_STORAGE_READER_CONTRACT = CHUNKED_STORAGE_READER_CONTRACT;
 exports.CONCURRENT_XML_FETCHES = CONCURRENT_XML_FETCHES;
@@ -2081,12 +2185,15 @@ exports.STORAGE_CONTRACT = STORAGE_CONTRACT;
 exports.STORAGE_ROUTER_CONTRACT = STORAGE_ROUTER_CONTRACT;
 exports.StorageClient = StorageClient;
 exports.assembleChunks = assembleChunks;
+exports.base64ToDataUri = base64ToDataUri;
 exports.chunkData = chunkData;
 exports.chunkDataForStorage = chunkDataForStorage;
 exports.computeTopLevelHash = computeTopLevelHash;
 exports.containsXmlReferences = containsXmlReferences;
+exports.detectFileTypeFromBase64 = detectFileTypeFromBase64;
 exports.detectStorageType = detectStorageType;
 exports.encodeStorageKeyForUrl = encodeStorageKeyForUrl;
+exports.fileToDataUri = fileToDataUri;
 exports.formatStorageKeyForDisplay = formatStorageKeyForDisplay;
 exports.generateStorageEmbedTag = generateStorageEmbedTag;
 exports.generateXmlMetadata = generateXmlMetadata;