Main -> Internal (#77)

* version poetry

* feat: add query method to Voice with tests

* updoate

* fix comit

* Fix - remove emojis from section headers and add public asset link

* Include changelog

* bump version

* feat: add customer trace id header

* feat: enhance header creation to accept custom headers

* docs: update changelog to include custom headers feature

* feat: implement context manager for setting customer trace id

* chore: reorganize imports in request_interface.py

* feat: update use_trace context manager to specify return type and add tests for trace id handling

* fix: update use_trace context manager to improve type hinting for trace_id

* fix: improve type hinting for current_trace_id in request_interface.py

* chore: reorder imports in request_interface.py for consistency

* fix: pass 0 float values (#73)

* fix: pass 0 float values

* chore: changelog

* chore: lint

* feat: update for new file system implementation (#75)

* feat: update for new file system implementation
* change base url
* only useful methods
* add docstrings
* fix files and typing
* fix cc reporter
* revert snake_case to camelCase
* Update CHANGELOG.md

* fix: Deleted unused import

---------

Co-authored-by: Guillem <[email protected]>
Co-authored-by: Harry Gardiner <[email protected]>
Co-authored-by: CodeBooster97 <[email protected]>
Co-authored-by: Lars <[email protected]>
Co-authored-by: Marcin Szleszynski <[email protected]>

Author: 5 people

.circleci/config.yml

@@ -38,8 +38,8 @@ jobs:
             ./cc-test-reporter before-build
             export AUDIO_STACK_DEV_KEY=$AFLR_API_KEY_PROD_TEST
             poetry run task test
-            ./cc-test-reporter after-build \
-            --coverage-input-type coverage.py --exit-code $?
+            # ./cc-test-reporter after-build \
+            # --coverage-input-type coverage.py --exit-code $?
   lint:
     docker:
       - image: cimg/python:3.8

CHANGELOG.md

@@ -4,6 +4,172 @@ All notable changes to `audiostack` will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.0.0] - 2025-07-29
+
+### 🆕 New Features
+
+#### File System Overhaul
+- **Complete file system redesign** with hierarchical folder structure
+- **New File.Item class** with comprehensive metadata:
+  - `fileId`: Unique file identifier
+  - `fileName`: Name of the file
+  - `url`: Download URL for the file
+  - `createdBy`: ID of user who created the file
+  - `lastModified`: Last modification timestamp
+  - `fileType`: File type information (dict with fileTypeId and name)
+  - `fileCategory`: Optional file category (can be null)
+  - `size`: File size as string
+  - `createdAt`: Creation timestamp
+  - `status`: File status (e.g., "uploaded")
+  - `duration`: Optional file duration (can be null)
+
+#### New Folder System
+- **New Folder.Item class** with hierarchical structure:
+  - `folderId`: Unique folder identifier
+  - `folderName`: Name of the folder
+  - `parentFolderId`: Parent folder ID (empty string for root)
+  - `createdBy`: ID of user who created the folder
+  - `lastModified`: Optional last modification timestamp (can be null)
+  - `createdAt`: Creation timestamp
+- **New Folder.ListResponse class** for folder listing operations with:
+  - `folders`: List of Folder.Item objects
+  - `files`: List of File.Item objects  
+  - `currentPathChain`: Dictionary containing path chain information
+- **New Folder.get_root_folder_id()` method to get root folder ID
+
+#### Enhanced File Operations
+- **Improved file upload process** with automatic polling for completion
+- **Timeout handling** using `TIMEOUT_THRESHOLD_S` for upload operations
+- **Better error handling** with specific error messages for upload failures
+
+### 🔄 API Changes
+
+#### File.create() Method
+- **BREAKING CHANGE**: Parameter names updated:
+  - `fileType` → **REMOVED** (no longer needed)
+- **New parameter**: `folderId` (Optional[UUID]) for specifying upload location
+- **Enhanced behavior**: Now polls for upload completion and returns complete file metadata
+
+#### File.get() Method
+- **BREAKING CHANGE**: Parameter name updated:
+  - `fileId` → `fileId` (kept camelCase)
+
+#### File.delete() Method
+- **BREAKING CHANGE**: Parameter names updated:
+  - `fileId` → `fileId` (kept camelCase)
+  - `folderId` → `folderId` (kept camelCase, optional, defaults to root folder)
+- **Return type change**: Now returns `None` instead of `APIResponseItem`
+
+#### File.Item Attributes
+- **BREAKING CHANGE**: All attribute names kept in camelCase:
+  - `fileId`: Unique file identifier
+  - `fileName`: Name of the file
+  - `url`: Download URL for the file
+  - `createdBy`: ID of user who created the file
+  - `lastModified`: Last modification timestamp
+  - `fileType`: File type information (dict with fileTypeId and name)
+  - `fileCategory`: Optional file category (can be null)
+  - `size`: File size as string
+  - `createdAt`: Creation timestamp
+  - `status`: File status (e.g., "uploaded")
+  - `duration`: Optional file duration (can be null)
+
+#### File.Item.download() Method
+- **BREAKING CHANGE**: Now requires `fileName` parameter (no longer optional)
+
+#### Folder Methods
+- **Folder.create(name, parentFolderId)** - Create new folder with optional parent
+- **Folder.get(folderId)** - Retrieve folder by ID  
+- **Folder.delete(folderId)** - Delete folder by ID
+- **Folder.get_root_folder_id()** - Get root folder ID
+
+### 🗑️ Removed Features
+
+#### Deprecated Methods
+- **File.modify()** - Completely removed
+- **File.get_file_categories()** - Completely removed
+- **File.get_category_id_by_name()** - Completely removed
+- **File.Item.delete()** - Instance method removed (use static method instead)
+
+#### Deprecated Classes
+- **Media class** - Completely removed
+- **File.List class** - Replaced with Folder.ListResponse
+- **Folder.List class** - Replaced with Folder.ListResponse
+
+#### Deprecated Inheritance
+- **File.Item** no longer inherits from `APIResponseItem`
+- **Folder.Item** no longer inherits from `APIResponseItem`
+
+### 🔧 Technical Improvements
+
+#### Code Quality
+- **Comprehensive docstrings** added to all methods and classes (PEP 257 compliant)
+- **Type hints** improved throughout the codebase
+- **Better error messages** with more descriptive exceptions
+- **Fixed typos** in error messages ("eixst" → "exist")
+
+#### Upload Process
+- **Fixed upload polling logic** with proper timeout handling
+- **Added mime_type parameter** to `send_upload_request` calls
+- **Improved upload status checking** with proper boolean logic
+
+### 📝 Migration Guide
+
+#### For File Operations
+```python
+# OLD
+file = File.create(localPath="file.mp3", uploadPath="name.mp3", fileType="audio")
+fileId = file.fileId
+file.delete(fileId=fileId, folderId=folderId)
+
+# NEW
+file = File.create(localPath="file.mp3", uploadPath="name.mp3", folderId=folderId)
+fileId = file.fileId
+File.delete(fileId=fileId, folderId=folderId)
+```
+
+#### For Folder Operations
+```python
+# OLD
+root = Folder.get_root()  # Returns Folder.Item
+folderId = root.currentPathChain["folderId"]
+
+# NEW
+folderId = Folder.get_root_folder_id()  # Returns string directly
+```
+
+#### For File Item Access
+```python
+# OLD
+fileId = file.fileId
+fileName = file.fileName
+
+# NEW
+fileId = file.fileId  # No change - kept camelCase
+fileName = file.fileName  # No change - kept camelCase
+```
+
+### ⚠️ Breaking Changes Summary
+
+1. **Parameter names** kept in camelCase (no changes to existing camelCase parameters)
+2. **Attribute names** kept in camelCase (no changes to existing camelCase attributes)
+3. **File.modify()** method completely removed
+4. **File.Item.delete()** instance method removed
+5. **Media class** completely removed
+6. **File.List and Folder.List** classes removed
+7. **Inheritance from APIResponseItem** removed for Item classes
+8. **File.create()** now requires `fileName` parameter in download method
+9. **Return types** changed for some methods (e.g., delete returns None)
+10. **New parameter**: `folderId` added to File.create() for specifying upload location
+
+### 🧪 Testing
+
+- **All existing tests updated** to work with new API
+- **New test patterns** for folder operations
+- **Conditional test skipping** for staging environment
+- **Improved test coverage** for new file system features
+
+
 ## [2.10.1] - 2025-02-24
 - Fixed logic that removed 0 float values from payload
 
@@ -128,4 +294,4 @@ Improved error messaging for Media files
 ### Fixes
 
 - Fixed missing argument in `content.list_modules`.
-- Fixed inclusion of missing `x-assume-org` header in `request_interface.download_url`.
+- Fixed inclusion of missing `x-assume-org` header in `request_interface.download_url`.

README.md

@@ -11,15 +11,15 @@
     <br>
 </p>
 
-## 🧐 About <a name = "about"></a>
+## About <a name = "about"></a>
 
 This repository is actively maintained by [Audiostack](https://audiostack.ai/). For examples, recipes and api reference see the [api.audio docs](https://docs.audiostack.ai/reference/quick-start). Feel free to get in touch with any questions or feedback!
 
-## :book:  Changelog
+## Changelog
 
 You can view [here](https://docs.audiostack.ai/changelog) our updated Changelog.
 
-## 🏁 Getting Started <a name = "getting_started"></a>
+## Getting Started <a name = "getting_started"></a>
 
 ### Installation
 
@@ -51,7 +51,7 @@ audiostack.assume_org_id = "your-org-id"
 
 ### Create your first audio asset
 
-#### ✍️ First, create a Script.
+#### First, create a Script.
 
 Audiostack Scripts are the first step in creating audio assets. Not only do they contain the text to be spoken, but also determine the final structure of our audio asset using the [Script Syntax](https://docs.audiostack.ai/docs/script-syntax).
 
@@ -71,7 +71,7 @@ We are excited to see what you'll create with our product!
 """)
 ```
 
-#### 🎤 Now, let's read it out load. 
+#### Now, let's read it out load. 
 
 We integrate all the major TTS voices in the market. You can browse them in our [voice library](https://library.audiostack.ai/).
 
@@ -88,7 +88,7 @@ When you listen to these files, you'll notice each of them has a certain silence
 tts = audiostack.Speech.TTS.remove_padding(speechId=tts.speechId)
 ```
 
-#### 🎛️ Now let's mix the speech we just created with a [sound template](https://library.audiostack.ai/sound).
+#### Now let's mix the speech we just created with a [sound template](https://library.audiostack.ai/sound).
 
 ```python
 mix = audiostack.Production.Mix.create(speechItem=tts, soundTemplate="chill_vibes")
@@ -101,18 +101,18 @@ You can list all the sound templates to see what segments are available or even
 Mixing comes with a lot of options to tune your audio to sound just right. 
 [More on this here.](https://docs.audiostack.ai/docs/advance-timing-parameters)
 
-#### 🎧 At this point, we can download the mix as a wave file, or convert it to another format.
+#### At this point, we can download the mix as a wave file, or convert it to another format.
 
 ```python
 enc = audiostack.Delivery.Encoder.encode_mix(productionItem=mix, preset="mp3_high")
 enc.download(fileName="example")
 ```
 
-Easy right? 🔮 This is the final result:
+Easy right? This is the final result:
 
-https://github.com/aflorithmic/audiostack-python/assets/64603095/6948cddb-4132-40a7-b84d-457f3fc0803d
+https://file.api.audio/pypi_example.mp3
 
-## :speedboat: More quickstarts <a name = "quickstarts"></a>
+## More quickstarts <a name = "quickstarts"></a>
 
 Get started with our [quickstart recipes](https://docs.audiostack.ai/docs/introduction).
 

audiostack/content/__init__.py

@@ -1,5 +1,4 @@
 from audiostack.content.file import File, Folder  # noqa: F401
-from audiostack.content.media import Media  # noqa: F401
 from audiostack.content.recommend import (  # noqa: F401
     RecommendIAB,
     RecommendMood,