hippius 0.2.39__py3-none-any.whl → 0.2.41__py3-none-any.whl

{hippius-0.2.39.dist-info → hippius-0.2.41.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hippius
-Version: 0.2.39
+Version: 0.2.41
 Summary: Python SDK and CLI for Hippius blockchain storage
 Home-page: https://github.com/thenervelab/hippius-sdk
 Author: Dubs

{hippius-0.2.39.dist-info → hippius-0.2.41.dist-info}/RECORD

@@ -1,10 +1,10 @@
-hippius_sdk/__init__.py,sha256=YRl6k_zVhkcQus3lgRi_IXvBPDgfvguZlJCtmOcp1CI,1474
+hippius_sdk/__init__.py,sha256=0Xf8Fnc93-TuSh6wLqELTb2OV2h1tfOmTnMDfe4i2RM,1474
 hippius_sdk/cli.py,sha256=aqKOYSBSWt7UhcpFt7wf9yIPJ3bznpsJ6ehOnuZ4usI,18235
 hippius_sdk/cli_assets.py,sha256=rjH3Z5A1CQr2d5CIAAAb0WMCjoZZlMWcdo0f93KqluE,635
 hippius_sdk/cli_handlers.py,sha256=HkZldE8ZDS6WHu8aSoeS_rYZ4kp3F-Kdzu-weY1c0vU,128258
 hippius_sdk/cli_parser.py,sha256=z7UvgWvvy04ey-R56qZiCqYc_9RaNq1rVDkQyXoK3JU,21100
 hippius_sdk/cli_rich.py,sha256=_jTBYMdHi2--fIVwoeNi-EtkdOb6Zy_O2TUiGvU3O7s,7324
-hippius_sdk/client.py,sha256=yS7fKAYIIjLReoUg1hppCD1sRy5MbSS81aLF_JLIZRE,23275
+hippius_sdk/client.py,sha256=n7QwLneWZym_eKN1fEAJWEi98nSJjdSpZJeEcFjZsqQ,24197
 hippius_sdk/config.py,sha256=Hf_aUYzG9ylzqauA_ABUSSB5mBTYbp-VtB36VQt2XDw,21981
 hippius_sdk/db/README.md,sha256=okDeI1qgkaZqXSlJ8L0xIE4UpuxO-qEGPIbXUvSHQjU,2030
 hippius_sdk/db/env.db.template,sha256=_6hEC3IvkzCDOAzG1_yJUKRUfCTMciNaJUicZpMCat4,217
@@ -13,12 +13,12 @@ hippius_sdk/db/migrations/20241202000001_switch_to_subaccount_encryption.sql,sha
 hippius_sdk/db/setup_database.sh,sha256=STp03qxkp2RmIVr6YZIcvQQm-_LLUOb6Jobh-52HWmg,3115
 hippius_sdk/db_utils.py,sha256=-x0rbN0as7Tn3PJPZBYCgreZe52FLH40ppA1TLxsg90,1851
 hippius_sdk/errors.py,sha256=LScJJmawVAx7aRzqqQguYSkf9iazSjEQEBNlD_GXZ6Y,1589
-hippius_sdk/ipfs.py,sha256=4g_NxQwmocssKu7b6kZ-ShAsF6fyKuj6IiYGCTNrpis,96918
-hippius_sdk/ipfs_core.py,sha256=X4yO9M_lSNtqiEJu5R-XX97eWzbL7GrN5MOk56p8pJk,12748
+hippius_sdk/ipfs.py,sha256=uBqjXzF8chKoFcyx9Jmuw9XCINf9qJ3Os1UBPdBsucc,100667
+hippius_sdk/ipfs_core.py,sha256=WG7bGLk-threOvmumizwh1dnd5zqbIkTXy1y-BRGayI,12789
 hippius_sdk/key_storage.py,sha256=SXFd6aGQw9MDLGX2vSBuAY7rdX-k5EvFm63z7_n-8yQ,8148
 hippius_sdk/substrate.py,sha256=4a7UIE4UqGcDW7luKTBgSDqfb2OIZusB39G1UiRs_YU,50158
 hippius_sdk/utils.py,sha256=rJ611yvwKSyiBpYU3w-SuyQxoghMGU-ePuslrPv5H5g,7388
-hippius-0.2.39.dist-info/METADATA,sha256=CbQCM8vIuc9v4rDhLma0swGipTVtQyrl7JI7mAA14dU,30088
-hippius-0.2.39.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
-hippius-0.2.39.dist-info/entry_points.txt,sha256=bFAZjW3vndretf9-8s587jA2ebMVI7puhn_lVs8jPc8,149
-hippius-0.2.39.dist-info/RECORD,,
+hippius-0.2.41.dist-info/METADATA,sha256=SSSssIaVQf94BZRTCMotY-zQGwUuByoPwA6svR7ufQE,30088
+hippius-0.2.41.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
+hippius-0.2.41.dist-info/entry_points.txt,sha256=bFAZjW3vndretf9-8s587jA2ebMVI7puhn_lVs8jPc8,149
+hippius-0.2.41.dist-info/RECORD,,

hippius_sdk/__init__.py

@@ -26,7 +26,7 @@ from hippius_sdk.config import (
 from hippius_sdk.ipfs import IPFSClient, S3PublishResult, S3DownloadResult
 from hippius_sdk.utils import format_cid, format_size, hex_to_ipfs_cid
 
-__version__ = "0.2.39"
+__version__ = "0.2.41"
 __all__ = [
     "HippiusClient",
     "IPFSClient",

hippius_sdk/client.py

@@ -3,7 +3,8 @@ Main client for the Hippius SDK.
 """
 
 import base64
-from typing import Any, Callable, Dict, List, Optional, Union
+import os
+from typing import Any, Callable, Dict, List, Optional, Union, AsyncIterator
 
 import nacl.secret
 import nacl.utils
@@ -118,7 +119,9 @@ class HippiusClient:
         """
         # Use the enhanced IPFSClient method directly with encryption parameter
         return await self.ipfs_client.upload_file(
-            file_path, encrypt=encrypt, seed_phrase=seed_phrase
+            file_path,
+            encrypt=encrypt,
+            seed_phrase=seed_phrase,
         )
 
     async def upload_directory(
@@ -517,25 +520,27 @@ class HippiusClient:
 
     async def s3_publish(
         self,
-        file_path: str,
+        content: Union[str, bytes, os.PathLike],
         encrypt: bool,
         seed_phrase: str,
         subaccount_id: str,
         bucket_name: str,
+        file_name: str = None,
         store_node: str = "http://localhost:5001",
         pin_node: str = "https://store.hippius.network",
         substrate_url: str = "wss://rpc.hippius.network",
         publish: bool = True,
     ) -> Union[S3PublishResult, S3PublishPin]:
         """
-        Publish a file to IPFS and the Hippius marketplace in one operation.
+        Publish content to IPFS and the Hippius marketplace in one operation.
 
         Uses a two-node architecture for optimal performance:
         1. Uploads to store_node (local) for immediate availability
         2. Pins to pin_node (remote) for persistence and backup
 
         Args:
-            file_path: Path to the file to publish
+            content: Either a file path (str/PathLike) or bytes content to publish
+            file_name: The original file name (required if content is bytes)
             encrypt: Whether to encrypt the file before uploading
             seed_phrase: Seed phrase for blockchain transaction signing
             subaccount_id: The subaccount/account identifier
@@ -556,46 +561,51 @@ class HippiusClient:
             ValueError: If encryption is requested but not available
         """
         return await self.ipfs_client.s3_publish(
-            file_path,
-            encrypt,
-            seed_phrase,
-            subaccount_id,
-            bucket_name,
-            store_node,
-            pin_node,
-            substrate_url,
-            publish,
+            content=content,
+            encrypt=encrypt,
+            seed_phrase=seed_phrase,
+            subaccount_id=subaccount_id,
+            bucket_name=bucket_name,
+            store_node=store_node,
+            pin_node=pin_node,
+            substrate_url=substrate_url,
+            publish=publish,
+            file_name=file_name,
         )
 
     async def s3_download(
         self,
         cid: str,
-        output_path: str,
-        subaccount_id: str,
-        bucket_name: str,
+        output_path: Optional[str] = None,
+        subaccount_id: Optional[str] = None,
+        bucket_name: Optional[str] = None,
         auto_decrypt: bool = True,
         download_node: str = "http://localhost:5001",
-    ) -> S3DownloadResult:
+        return_bytes: bool = False,
+        streaming: bool = False,
+    ) -> Union[S3DownloadResult, bytes, AsyncIterator[bytes]]:
         """
-        Download a file from IPFS with automatic decryption.
+        Download content from IPFS with flexible output options and automatic decryption.
 
-        This method uses the download_node for immediate availability and automatically
-        manages decryption keys per account+bucket combination:
-        - Downloads the file from the specified download_node (local by default)
-        - If auto_decrypt=True, attempts to decrypt using stored keys for the account+bucket
-        - Falls back to client encryption key if key storage is not available
-        - Returns the file in decrypted form if decryption succeeds
+        This method provides multiple output modes:
+        1. File output: Downloads to specified path (default mode)
+        2. Bytes output: Returns decrypted bytes in memory (return_bytes=True)
+        3. Streaming output: Returns raw streaming iterator from IPFS node (streaming=True)
 
         Args:
             cid: Content Identifier (CID) of the file to download
-            output_path: Path where the downloaded file will be saved
-            subaccount_id: The subaccount/account identifier
-            bucket_name: The bucket name for key isolation
+            output_path: Path where the downloaded file will be saved (None for bytes/streaming)
+            subaccount_id: The subaccount/account identifier (required for decryption)
+            bucket_name: The bucket name for key isolation (required for decryption)
             auto_decrypt: Whether to attempt automatic decryption (default: True)
             download_node: IPFS node URL for download (default: local node)
+            return_bytes: If True, return bytes instead of saving to file
+            streaming: If True, return raw streaming iterator from IPFS (no decryption)
 
         Returns:
-            S3DownloadResult: Object containing download info and decryption status
+            S3DownloadResult: Download info and decryption status (default)
+            bytes: Raw decrypted content when return_bytes=True
+            AsyncIterator[bytes]: Raw streaming iterator when streaming=True
 
         Raises:
             HippiusIPFSError: If IPFS download fails
@@ -603,5 +613,12 @@ class HippiusClient:
             ValueError: If decryption fails
         """
         return await self.ipfs_client.s3_download(
-            cid, output_path, subaccount_id, bucket_name, auto_decrypt, download_node
+            cid=cid,
+            output_path=output_path,
+            subaccount_id=subaccount_id,
+            bucket_name=bucket_name,
+            auto_decrypt=auto_decrypt,
+            download_node=download_node,
+            return_bytes=return_bytes,
+            streaming=streaming,
         )

hippius_sdk/ipfs.py

@@ -1,6 +1,7 @@
 """
 IPFS operations for the Hippius SDK.
 """
+
 import asyncio
 import base64
 import hashlib
@@ -12,7 +13,7 @@ import shutil
 import tempfile
 import time
 import uuid
-from typing import Any, Callable, Dict, List, Optional, Union
+from typing import Any, Callable, Dict, List, Optional, Union, AsyncIterator
 
 import httpx
 from pydantic import BaseModel
@@ -129,7 +130,7 @@ class IPFSClient:
 
         try:
             self.client = AsyncIPFSClient(api_url=api_url, gateway=self.gateway)
-        except httpx.ConnectError as e:
+        except httpx.ConnectError:
             print(
                 f"Warning: Falling back to local IPFS daemon, but still using gateway={self.gateway}"
             )
@@ -241,6 +242,7 @@ class IPFSClient:
         encrypt: Optional[bool] = None,
         max_retries: int = 3,
         seed_phrase: Optional[str] = None,
+        file_name: str = None,
     ) -> Dict[str, Any]:
         """
         Upload a file to IPFS with optional encryption.
@@ -251,6 +253,7 @@ class IPFSClient:
             encrypt: Whether to encrypt the file (overrides default)
             max_retries: Maximum number of retry attempts (default: 3)
             seed_phrase: Optional seed phrase to use for blockchain interactions (uses config if None)
+            file_name: The original file name
 
         Returns:
             Dict[str, Any]: Dictionary containing:
@@ -278,7 +281,7 @@ class IPFSClient:
             )
 
         # Get file info before upload
-        filename = os.path.basename(file_path)
+        file_name = file_name if file_name else os.path.basename(file_path)
         size_bytes = os.path.getsize(file_path)
 
         # If encryption is requested, encrypt the file first
@@ -303,7 +306,10 @@ class IPFSClient:
                 # Use the original file for upload
                 upload_path = file_path
 
-            result = await self.client.add_file(upload_path)
+            result = await self.client.add_file(
+                upload_path,
+                file_name=file_name,
+            )
             cid = result["Hash"]
 
         finally:
@@ -314,7 +320,7 @@ class IPFSClient:
         # Format the result
         result = {
             "cid": cid,
-            "filename": filename,
+            "filename": file_name,
             "size_bytes": size_bytes,
             "encrypted": should_encrypt,
         }
@@ -1411,7 +1417,7 @@ class IPFSClient:
 
             for i, chunk in enumerate(reconstructed_chunks):
                 if verbose and i % 10 == 0:
-                    print(f"Processing chunk {i+1}/{len(reconstructed_chunks)}...")
+                    print(f"Processing chunk {i + 1}/{len(reconstructed_chunks)}...")
 
                 # For all chunks except the last one, use full chunk size
                 if i < len(reconstructed_chunks) - 1:
@@ -1750,8 +1756,9 @@ class IPFSClient:
                 # Record the child files that were processed
                 result["child_files"] = child_files
         except Exception as e:
-            print(f"Warning: Failed to check if CID is a directory: {e}")
-            # Continue with regular file unpin
+            print(
+                f"Warning: Failed to check if CID is a directory: {e}"
+            )  # Continue with regular file unpin
 
         # Now unpin the main file/directory
         if unpin:
@@ -1821,7 +1828,8 @@ class IPFSClient:
         cancel_from_blockchain: bool = True,
         parallel_limit: int = 20,
         seed_phrase: Optional[str] = None,
-        metadata_timeout: int = 30,  # Timeout in seconds for metadata fetch
+        metadata_timeout: int = 30,
+        # Timeout in seconds for metadata fetch
     ) -> bool:
         """
         Delete an erasure-coded file, including all its chunks in parallel.
@@ -1863,8 +1871,7 @@ class IPFSClient:
                 except asyncio.TimeoutError:
                     print(
                         f"Timed out after {metadata_timeout}s waiting for metadata download"
-                    )
-                    # We'll continue with blockchain cancellation even without metadata
+                    )  # We'll continue with blockchain cancellation even without metadata
             except json.JSONDecodeError as e:
                 # If we can't parse the metadata JSON, record the error but continue
                 print(f"Error parsing metadata JSON: {e}")
@@ -1960,7 +1967,7 @@ class IPFSClient:
 
     async def s3_publish(
         self,
-        file_path: str,
+        content: Union[str, bytes, os.PathLike],
         encrypt: bool,
         seed_phrase: str,
         subaccount_id: str,
@@ -1969,9 +1976,10 @@ class IPFSClient:
         pin_node: str = "https://store.hippius.network",
         substrate_url: str = "wss://rpc.hippius.network",
         publish: bool = True,
+        file_name: str = None,
     ) -> Union[S3PublishResult, S3PublishPin]:
         """
-        Publish a file to IPFS and the Hippius marketplace in one operation.
+        Publish content to IPFS and the Hippius marketplace in one operation.
 
         This method uses a two-node architecture for optimal performance:
         1. Uploads to store_node (local) for immediate availability
@@ -1984,8 +1992,8 @@ class IPFSClient:
         - Always uses the most recent key for an account+bucket combination
 
         Args:
-            file_path: Path to the file to publish
-            encrypt: Whether to encrypt the file before uploading
+            content: Either a file path (str/PathLike) or bytes content to publish
+            encrypt: Whether to encrypt the content before uploading
             seed_phrase: Seed phrase for blockchain transaction signing
             subaccount_id: The subaccount/account identifier
             bucket_name: The bucket name for key isolation
@@ -1993,24 +2001,47 @@ class IPFSClient:
             pin_node: IPFS node URL for backup pinning (default: remote service)
             substrate_url: the substrate url to connect to for the storage request
             publish: Whether to publish to blockchain (True) or just upload to IPFS (False)
+            file_name: The original file name (required if content is bytes)
 
         Returns:
             S3PublishResult: Object containing CID, file info, and transaction hash when publish=True
-            S3PublishPin: Object containing CID, subaccount, file_path, pin_node, substrate_url when publish=False
+            S3PublishPin: Object containing CID, subaccount, content info, pin_node, substrate_url when publish=False
 
         Raises:
             HippiusIPFSError: If IPFS operations (add or pin) fail
             HippiusSubstrateError: If substrate call fails
-            FileNotFoundError: If the file doesn't exist
-            ValueError: If encryption is requested but not available
+            FileNotFoundError: If the file doesn't exist (when content is a path)
+            ValueError: If encryption is requested but not available, or if file_name is missing for bytes content
         """
-        # Check if file exists and get initial info
-        if not os.path.exists(file_path):
-            raise FileNotFoundError(f"File {file_path} not found")
+        # Determine if content is a file path or bytes
+        is_file_path = isinstance(content, (str, os.PathLike))
+
+        if is_file_path:
+            # Handle file path input
+            file_path = str(content)
+            if not os.path.exists(file_path):
+                raise FileNotFoundError(f"File {file_path} not found")
+
+            # Get file info
+            filename = file_name or os.path.basename(file_path)
+            size_bytes = os.path.getsize(file_path)
+
+            # Read file content into memory
+            with open(file_path, "rb") as f:
+                content_bytes = f.read()
+        else:
+            # Handle bytes input
+            if not isinstance(content, bytes):
+                raise ValueError(
+                    f"Content must be str, PathLike, or bytes, got {type(content)}"
+                )
 
-        # Get file info
-        filename = os.path.basename(file_path)
-        size_bytes = os.path.getsize(file_path)
+            if not file_name:
+                raise ValueError("file_name is required when content is bytes")
+
+            filename = file_name
+            content_bytes = content
+            size_bytes = len(content_bytes)
 
         # Handle encryption if requested with automatic key management
         encryption_key_used = None
@@ -2048,19 +2079,11 @@ class IPFSClient:
                     encryption_key_bytes = base64.b64decode(new_key_b64)
                     encryption_key_used = new_key_b64
 
-                # Read file content into memory
-                with open(file_path, "rb") as f:
-                    file_data = f.read()
-
                 # Encrypt the data using the key from key storage
                 import nacl.secret
 
                 box = nacl.secret.SecretBox(encryption_key_bytes)
-                encrypted_data = box.encrypt(file_data)
-
-                # Overwrite the original file with encrypted data
-                with open(file_path, "wb") as f:
-                    f.write(encrypted_data)
+                content_bytes = box.encrypt(content_bytes)
             else:
                 # Fallback to the original encryption system if key_storage is not available
                 if not self.encryption_available:
@@ -2068,16 +2091,8 @@ class IPFSClient:
                         "Encryption requested but not available. Either install key storage with 'pip install hippius_sdk[key_storage]' or configure an encryption key with 'hippius keygen --save'"
                     )
 
-                # Read file content into memory
-                with open(file_path, "rb") as f:
-                    file_data = f.read()
-
                 # Encrypt the data using the client's encryption key
-                encrypted_data = self.encrypt_data(file_data)
-
-                # Overwrite the original file with encrypted data
-                with open(file_path, "wb") as f:
-                    f.write(encrypted_data)
+                content_bytes = self.encrypt_data(content_bytes)
 
                 # Store the encryption key for the result
                 encryption_key_used = (
@@ -2089,12 +2104,15 @@ class IPFSClient:
         # Step 1: Upload to store_node (local) for immediate availability
         try:
             store_client = AsyncIPFSClient(api_url=store_node)
-            result = await store_client.add_file(file_path)
+            result = await store_client.add_bytes(
+                content_bytes,
+                filename=filename,
+            )
             cid = result["Hash"]
-            logger.info(f"File uploaded to store node {store_node} with CID: {cid}")
+            logger.info(f"Content uploaded to store node {store_node} with CID: {cid}")
         except Exception as e:
             raise HippiusIPFSError(
-                f"Failed to upload file to store node {store_node}: {str(e)}"
+                f"Failed to upload content to store node {store_node}: {str(e)}"
             )
 
         # Step 2: Pin to pin_node (remote) for persistence and backup
@@ -2104,7 +2122,7 @@ class IPFSClient:
             logger.info(f"File pinned to backup node {pin_node}")
         except Exception as e:
             raise HippiusIPFSError(
-                f"Failed to pin file to store node {store_node}: {str(e)}"
+                f"Failed to pin content to pin node {pin_node}: {str(e)}"
             )
 
         # Conditionally publish to substrate marketplace based on publish flag
@@ -2112,7 +2130,8 @@ class IPFSClient:
             try:
                 # Pass the seed phrase directly to avoid password prompts for encrypted config
                 substrate_client = SubstrateClient(
-                    seed_phrase=seed_phrase, url=substrate_url
+                    seed_phrase=seed_phrase,
+                    url=substrate_url,
                 )
                 logger.info(
                     f"Submitting storage request to substrate for file: {filename}, CID: {cid}"
@@ -2161,7 +2180,7 @@ class IPFSClient:
             return S3PublishPin(
                 cid=cid,
                 subaccount=subaccount_id,
-                file_path=file_path,
+                file_path=filename,
                 pin_node=pin_node,
                 substrate_url=substrate_url,
             )
@@ -2169,49 +2188,80 @@ class IPFSClient:
     async def s3_download(
         self,
         cid: str,
-        output_path: str,
-        subaccount_id: str,
-        bucket_name: str,
+        output_path: Optional[str] = None,
+        subaccount_id: Optional[str] = None,
+        bucket_name: Optional[str] = None,
         auto_decrypt: bool = True,
         download_node: str = "http://localhost:5001",
-    ) -> S3DownloadResult:
+        return_bytes: bool = False,
+        streaming: bool = False,
+    ) -> Union[S3DownloadResult, bytes, AsyncIterator[bytes]]:
         """
-        Download a file from IPFS with automatic decryption.
+        Download content from IPFS with flexible output options and automatic decryption.
 
-        This method uses the download_node for immediate availability and automatically
-        manages decryption keys per account+bucket combination:
-        - Downloads the file from the specified download_node (local by default)
-        - If auto_decrypt=True, attempts to decrypt using stored keys for the account+bucket
-        - Falls back to client encryption key if key storage is not available
-        - Returns the file in decrypted form if decryption succeeds
+        This method provides multiple output modes:
+        1. File output: Downloads to specified path (default mode)
+        2. Bytes output: Returns decrypted bytes in memory (return_bytes=True)
+        3. Streaming output: Returns raw streaming iterator from IPFS node (streaming=True)
 
         Args:
             cid: Content Identifier (CID) of the file to download
-            output_path: Path where the downloaded file will be saved
-            subaccount_id: The subaccount/account identifier
-            bucket_name: The bucket name for key isolation
+            output_path: Path where the downloaded file will be saved (None for bytes/streaming)
+            subaccount_id: The subaccount/account identifier (required for decryption)
+            bucket_name: The bucket name for key isolation (required for decryption)
             auto_decrypt: Whether to attempt automatic decryption (default: True)
             download_node: IPFS node URL for download (default: local node)
+            return_bytes: If True, return bytes instead of saving to file
+            streaming: If True, return raw streaming iterator from IPFS (no decryption)
 
         Returns:
-            S3DownloadResult: Object containing download info and decryption status
+            S3DownloadResult: Download info and decryption status (default)
+            bytes: Raw decrypted content when return_bytes=True
+            AsyncIterator[bytes]: Raw streaming iterator when streaming=True
 
         Raises:
             HippiusIPFSError: If IPFS download fails
             FileNotFoundError: If the output directory doesn't exist
-            ValueError: If decryption fails
+            ValueError: If decryption fails or invalid parameter combinations
         """
+        # Validate parameter combinations
+        if streaming and return_bytes:
+            raise ValueError("Cannot specify both streaming and return_bytes")
+
+        if streaming and (auto_decrypt or subaccount_id or bucket_name):
+            logger.warning(
+                "streaming=True ignores decryption parameters - returns raw encrypted stream"
+            )
+
+        if streaming:
+            # Return raw streaming iterator from IPFS node - no processing
+            # _get_ipfs_stream is an async generator, return it directly
+            async def streaming_wrapper():
+                async for chunk in self._get_ipfs_stream(cid, download_node):
+                    yield chunk
+            return streaming_wrapper()
+
         start_time = time.time()
 
+        # Validate required parameters for decryption
+        if auto_decrypt and (not subaccount_id or not bucket_name):
+            raise ValueError(
+                "subaccount_id and bucket_name are required when auto_decrypt=True"
+            )
+
+        if not return_bytes and not output_path:
+            raise ValueError("output_path is required when not using return_bytes mode")
+
         # Download the file directly into memory from the specified download_node
         try:
-            # Create parent directories if they don't exist
-            os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+            # Create parent directories if they don't exist (only for file output mode)
+            if not return_bytes:
+                os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
 
             download_client = AsyncIPFSClient(api_url=download_node)
 
             download_url = f"{download_node.rstrip('/')}/api/v0/cat?arg={cid}"
-            
+
             # Download file into memory
             file_data = bytearray()
             async with download_client.client.stream("POST", download_url) as response:
@@ -2221,7 +2271,9 @@ class IPFSClient:
 
             # Convert to bytes for consistency
             file_data = bytes(file_data)
-            logger.info(f"File downloaded from {download_node} with CID: {cid} ({len(file_data)} bytes)")
+            logger.info(
+                f"File downloaded from {download_node} with CID: {cid} ({len(file_data)} bytes)"
+            )
 
         except Exception as e:
             raise HippiusIPFSError(
@@ -2299,8 +2351,7 @@ class IPFSClient:
                             except Exception as decrypt_error:
                                 logger.debug(
                                     f"Decryption failed with stored key: {decrypt_error}"
-                                )
-                                # Continue to try fallback decryption
+                                )  # Continue to try fallback decryption
                         else:
                             logger.debug(
                                 "No encryption key found for account+bucket combination"
@@ -2343,20 +2394,58 @@ class IPFSClient:
                 elif not decryption_attempted:
                     logger.debug("No decryption attempted - no keys available")
 
-        # Write the final data (encrypted or decrypted) to disk once
-        with open(output_path, "wb") as f:
-            f.write(final_data)
+        # Handle output based on mode
+        if return_bytes:
+            # Return bytes directly
+            return final_data
+        else:
+            # Write the final data (encrypted or decrypted) to disk once
+            with open(output_path, "wb") as f:
+                f.write(final_data)
+
+            # Get final file info
+            size_bytes = len(final_data)
+            elapsed_time = time.time() - start_time
 
-        # Get final file info
-        size_bytes = len(final_data)
-        elapsed_time = time.time() - start_time
+            return S3DownloadResult(
+                cid=cid,
+                output_path=output_path,
+                size_bytes=size_bytes,
+                size_formatted=self.format_size(size_bytes),
+                elapsed_seconds=round(elapsed_time, 2),
+                decrypted=decrypted,
+                encryption_key=encryption_key_used,
+            )
 
-        return S3DownloadResult(
-            cid=cid,
-            output_path=output_path,
-            size_bytes=size_bytes,
-            size_formatted=self.format_size(size_bytes),
-            elapsed_seconds=round(elapsed_time, 2),
-            decrypted=decrypted,
-            encryption_key=encryption_key_used,
-        )
+    async def _get_ipfs_stream(
+        self, cid: str, download_node: str
+    ) -> AsyncIterator[bytes]:
+        """
+        Get a raw streaming iterator from IPFS node.
+
+        This method returns the raw encrypted stream directly from the IPFS node
+        without any processing, decryption, or temporary file operations.
+
+        Args:
+            cid: Content Identifier (CID) of the file to stream
+            download_node: IPFS node URL for download
+
+        Returns:
+            AsyncIterator[bytes]: Raw streaming iterator from IPFS
+
+        Raises:
+            HippiusIPFSError: If IPFS stream fails
+        """
+        try:
+            download_client = AsyncIPFSClient(api_url=download_node)
+            download_url = f"{download_node.rstrip('/')}/api/v0/cat?arg={cid}"
+
+            async with download_client.client.stream("POST", download_url) as response:
+                response.raise_for_status()
+                logger.info(f"Started streaming from {download_node} for CID: {cid}")
+
+                async for chunk in response.aiter_bytes(chunk_size=8192):
+                    yield chunk
+
+        except Exception as e:
+            raise HippiusIPFSError(f"Failed to stream from {download_node}: {str(e)}")

hippius_sdk/ipfs_core.py

@@ -48,11 +48,16 @@ class AsyncIPFSClient:
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         await self.close()
 
-    async def add_file(self, file_path: str) -> Dict[str, Any]:
+    async def add_file(
+        self,
+        file_path: str,
+        file_name: str = None,
+    ) -> Dict[str, Any]:
         """
         Add a file to IPFS.
 
         Args:
+            file_name: Name of the file
             file_path: Path to the file to add
 
         Returns:
@@ -60,9 +65,9 @@ class AsyncIPFSClient:
         """
         with open(file_path, "rb") as f:
             file_content = f.read()
-            filename = os.path.basename(file_path)
-            # Specify file with name and content type to ensure consistent handling
-            files = {"file": (filename, file_content, "application/octet-stream")}
+            file_name = file_name if file_name else os.path.basename(file_path)
+            files = {"file": (file_name, file_content, "application/octet-stream")}
+
             # Explicitly set wrap-with-directory=false to prevent wrapping in directory
             response = await self.client.post(
                 f"{self.api_url}/api/v0/add?wrap-with-directory=false&cid-version=1",