@net-protocol/storage 0.1.12 → 0.1.14

package/README.md

@@ -32,8 +32,8 @@ Net Storage supports three storage patterns for different file sizes:
 
 ### XML Storage
 
-**Best for**: Large files (> 20KB) or files containing XML references  
-**How it works**: Splits large files into 80KB pieces, stores each using ChunkedStorage (compressed and chunked into 20KB pieces), maintains references as XML metadata  
+**Best for**: Large files (> 20KB) or files containing XML references
+**How it works**: Splits large files into 80KB pieces (configurable via `chunkSize`), stores each using ChunkedStorage (compressed and chunked into 20KB pieces), maintains references as XML metadata
 **Use cases**: Videos, large images, datasets, any large file
 
 ## What can you do with this package?
@@ -133,38 +133,24 @@ function XmlComponent() {
   return <div>{data}</div>;
 }
 
-// XML storage with format options
-function XmlWithFormats() {
-  // Return as tuple format with hex output
-  const { data: tupleData } = useXmlStorage({
+// XML storage with options
+function XmlWithOptions() {
+  // With hex output (default)
+  const { data: hexData, isXml } = useXmlStorage({
     chainId: 8453,
     key: "my-xml-key",
     operatorAddress: "0x...",
-    returnFormat: "tuple", // Returns [text, data] tuple
     outputFormat: "hex", // Data is hex string (default)
     useRouter: true, // Use StorageRouter for automatic detection
   });
 
-  // Return as tuple format with string output
-  const { data: tupleStringData } = useXmlStorage({
+  // With string output
+  const { data: stringData } = useXmlStorage({
     chainId: 8453,
     key: "my-xml-key",
     operatorAddress: "0x...",
-    returnFormat: "tuple",
     outputFormat: "string", // Data is plain string
   });
-
-  // Return as object format (default)
-  const {
-    data: objectData,
-    filename,
-    isXml,
-  } = useXmlStorage({
-    chainId: 8453,
-    key: "my-xml-key",
-    operatorAddress: "0x...",
-    returnFormat: "object", // Returns { data, filename, isLoading, error, isXml }
-  });
 }
 
 // Storage from router (handles chunked storage)
@@ -228,6 +214,7 @@ import {
   fileToDataUri,
   detectFileTypeFromBase64,
   base64ToDataUri,
+  OPTIMAL_CHUNK_SIZE,
 } from "@net-protocol/storage";
 
 // Generate storage key bytes
@@ -242,8 +229,11 @@ const assembled = assembleChunks(chunks);
 // Parse XML references
 const references = parseNetReferences('<net k="hash" v="0.0.1" />');
 
-// Process data for XML storage
-const result = processDataForStorage(data, operatorAddress);
+// Process data for XML storage (default 80KB chunk size)
+const result = processDataForStorage(data, operatorAddress, storageKey);
+
+// Process with custom chunk size (40KB)
+const result2 = processDataForStorage(data, operatorAddress, storageKey, 40000);
 ```
 
 ### File Utilities
@@ -297,6 +287,11 @@ const dataUri = base64ToDataUri(base64Data);
 - `getForOperatorAndKey(params)` - Get storage by operator and key
 - `readStorageData(params)` - Read with XML resolution
 - `readChunkedStorage(params)` - Read chunked storage with decompression
+- `prepareXmlStorage(params)` - Prepare XML storage transactions (supports optional `chunkSize`)
+
+### Constants
+
+- `OPTIMAL_CHUNK_SIZE` - Default chunk size for XML storage (80000 bytes)
 
 ## Storage Types
 

package/dist/index.d.mts

@@ -208,6 +208,17 @@ declare function formatStorageKeyForDisplay(storageKey: string): {
  * @param keyFormat - Optional format override: "raw" to always convert, "bytes32" to use as-is, undefined for auto-detect
  */
 declare function getStorageKeyBytes(input: string, keyFormat?: "raw" | "bytes32"): string;
+/**
+ * Extract a storage key from a message's hex-encoded data field.
+ *
+ * Follows the same detection heuristic as the Net website:
+ * a value is treated as a storage key reference if the decoded string
+ * starts with "netid-" or is 32 characters or fewer.
+ *
+ * @param data - The hex-encoded data field from a NetMessage
+ * @returns The decoded storage key string, or null if not a storage reference
+ */
+declare function extractStorageKeyFromMessageData(data: `0x${string}` | string | undefined): string | null;
 /**
  * Encodes a storage key for use in URL paths.
  *
@@ -514,4 +525,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 { BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, MAX_XML_DEPTH, OPTIMAL_CHUNK_SIZE, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, StorageClientOptions, StorageData, type StreamingChunkResult, type StreamingProcessResult, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, estimateChunkCount, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, isBinaryFile, parseNetReferences, processDataForStorage, processFileStreaming, processFileStreamingComplete, readFileSlice, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, validateDataSize };
+export { BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, MAX_XML_DEPTH, OPTIMAL_CHUNK_SIZE, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, StorageClientOptions, StorageData, type StreamingChunkResult, type StreamingProcessResult, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, estimateChunkCount, extractStorageKeyFromMessageData, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, isBinaryFile, parseNetReferences, processDataForStorage, processFileStreaming, processFileStreamingComplete, readFileSlice, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, validateDataSize };

package/dist/index.d.ts

@@ -208,6 +208,17 @@ declare function formatStorageKeyForDisplay(storageKey: string): {
  * @param keyFormat - Optional format override: "raw" to always convert, "bytes32" to use as-is, undefined for auto-detect
  */
 declare function getStorageKeyBytes(input: string, keyFormat?: "raw" | "bytes32"): string;
+/**
+ * Extract a storage key from a message's hex-encoded data field.
+ *
+ * Follows the same detection heuristic as the Net website:
+ * a value is treated as a storage key reference if the decoded string
+ * starts with "netid-" or is 32 characters or fewer.
+ *
+ * @param data - The hex-encoded data field from a NetMessage
+ * @returns The decoded storage key string, or null if not a storage reference
+ */
+declare function extractStorageKeyFromMessageData(data: `0x${string}` | string | undefined): string | null;
 /**
  * Encodes a storage key for use in URL paths.
  *
@@ -514,4 +525,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 { BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, MAX_XML_DEPTH, OPTIMAL_CHUNK_SIZE, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, StorageClientOptions, StorageData, type StreamingChunkResult, type StreamingProcessResult, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, estimateChunkCount, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, isBinaryFile, parseNetReferences, processDataForStorage, processFileStreaming, processFileStreamingComplete, readFileSlice, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, validateDataSize };
+export { BulkStorageKey, CHUNKED_STORAGE_CONTRACT, CHUNKED_STORAGE_READER_CONTRACT, CONCURRENT_XML_FETCHES, MAX_XML_DEPTH, OPTIMAL_CHUNK_SIZE, SAFE_STORAGE_READER_CONTRACT, STORAGE_CONTRACT, STORAGE_ROUTER_CONTRACT, StorageClient, StorageClientOptions, StorageData, type StreamingChunkResult, type StreamingProcessResult, assembleChunks, base64ToDataUri, chunkData, chunkDataForStorage, computeTopLevelHash, containsXmlReferences, detectFileTypeFromBase64, detectStorageType, encodeStorageKeyForUrl, estimateChunkCount, extractStorageKeyFromMessageData, fileToDataUri, formatStorageKeyForDisplay, generateStorageEmbedTag, generateXmlMetadata, generateXmlMetadataWithSource, getChunkCount, getReferenceKey, getStorageKeyBytes, isBinaryFile, parseNetReferences, processDataForStorage, processFileStreaming, processFileStreamingComplete, readFileSlice, resolveOperator, resolveXmlRecursive, shouldSuggestXmlStorage, validateDataSize };

package/dist/index.js

@@ -629,6 +629,17 @@ function getStorageKeyBytes(input, keyFormat) {
   }
   return input.length > 32 ? core.keccak256HashString(input.toLowerCase()) : core.toBytes32(input.toLowerCase());
 }
+function extractStorageKeyFromMessageData(data) {
+  if (!data || data === "0x" || !data.startsWith("0x")) return null;
+  try {
+    const decoded = viem.hexToString(data);
+    if (decoded.startsWith("netid-") || decoded.length <= 32) {
+      return decoded;
+    }
+  } catch {
+  }
+  return null;
+}
 function encodeStorageKeyForUrl(key) {
   return encodeURIComponent(key);
 }
@@ -1791,6 +1802,7 @@ exports.detectFileTypeFromBase64 = detectFileTypeFromBase64;
 exports.detectStorageType = detectStorageType;
 exports.encodeStorageKeyForUrl = encodeStorageKeyForUrl;
 exports.estimateChunkCount = estimateChunkCount;
+exports.extractStorageKeyFromMessageData = extractStorageKeyFromMessageData;
 exports.fileToDataUri = fileToDataUri;
 exports.formatStorageKeyForDisplay = formatStorageKeyForDisplay;
 exports.generateStorageEmbedTag = generateStorageEmbedTag;