n8n-nodes-starter/docs/enhancement_requirements.md

# Functional and Non-Functional Requirements

## 1. Functional Requirements (FRs)

The n8n Suno AI node should provide the following functionalities:

### FR1: User Authentication
- **FR1.1:** The system must allow users to authenticate with the Suno AI service using their credentials (email and password).
- **FR1.2:** Authentication status should be managed (e.g., session token stored and used for subsequent API calls). (Currently mocked)

### FR2: Music Generation
- **FR2.1: Generate Song from Text Prompt:**
    - The node must allow users to submit a text prompt.
    - The node should allow specifying additional options (e.g., style, mood, instrumental - to be defined based on Suno API capabilities).
    - The system should initiate a music generation job via the Suno API.
    - The system should return a job identifier and initial status. (Currently mocked job ID and status)
- **FR2.2: Upload Track Reference (for generation):**
    - The node must allow users to specify a file path for an audio track to be used as a reference (e.g., for style transfer or continuation - dependent on Suno API).
    - The system should upload this track and return a reference identifier or initiate a job. (Currently mocked)

### FR3: Job & Track Management
- **FR3.1: Get Track/Job Status:**
    - The node must allow users to query the status of a specific generation job or track using its ID.
    - The system should return the current status (e.g., queued, generating, complete, failed) and progress if available. (Currently mocked with state changes)
- **FR3.2: Download Generated Track:**
    - Once a track is successfully generated, the node must allow users to download the audio file (e.g., MP3, WAV - dependent on Suno API).
    - The system should provide the audio data as a binary output. (Currently mocked with dummy binary data)
- **FR3.3: List Previous Songs:**
    - The node must allow users to retrieve a list of their previously generated songs.
    - The system should return track details (e.g., ID, title, status, URLs). (Currently mocked)

### FR4: Workflow Triggers
- **FR4.1: Trigger on Track Generation Complete:**
    - The system must provide a trigger that activates when a specific music generation job/track is complete.
    - The trigger should output details of the completed track. (Currently mocked polling)
- **FR4.2: Trigger on New Song Available:**
    - The system must provide a trigger that activates when a new song becomes available in the user's Suno AI library.
    - The trigger should output details of the new song(s). (Currently mocked polling, needs robust new song detection)

### FR5: (Placeholder) Other Suno API Features
- (e.g., Select Voice/Style - `selectVoice` is a placeholder in `sunoApi.ts`) - to be defined if Suno API supports these as distinct actions relevant to the n8n node.

## 2. Non-Functional Requirements (NFRs)

### NFR1: Reliability
- **NFR1.1:** All API interactions must include robust error handling.
- **NFR1.2:** Clear and informative error messages should be provided to the n8n user in case of failures.
- **NFR1.3:** Polling triggers should be fault-tolerant (e.g., handle temporary API unavailability gracefully).
- **NFR1.4:** The node should correctly manage authentication state and attempt re-authentication or token refresh if necessary and feasible (actual mechanism TBD based on Suno API).

### NFR2: Maintainability
- **NFR2.1:** Code must be clean, well-organized, and follow established TypeScript best practices. Module separation should be preserved.
- **NFR2.2:** Comprehensive JSDoc comments for all functions, classes, interfaces, and type properties.
- **NFR2.3:** The `docs/dev-log.md` should be kept up-to-date with significant decisions and progress.
- **NFR2.4:** Configuration and magic strings should be minimized, using constants or configuration variables where appropriate.

### NFR3: Usability (n8n User Experience)
- **NFR3.1:** Node parameters should be clearly named and described in the n8n UI.
- **NFR3.2:** Operations should be logically grouped and named.
- **NFR3.3:** Output data from node operations and triggers should be well-structured and useful for downstream n8n nodes.
- **NFR3.4:** Placeholder text and default values for node parameters should be helpful.

### NFR4: Performance
- **NFR4.1:** API calls should be made efficiently. Avoid unnecessary calls. (Dependent on actual Suno API structure).
- **NFR4.2:** Mocked API calls (current state) should be lightweight and fast to not hinder development or testing.
- **NFR4.3:** For operations involving file handling (e.g., download, upload reference), streams should be considered if the actual API supports them and files can be large, to manage memory efficiently.

### NFR5: Testability
- **NFR5.1:** Code should be structured to facilitate unit and integration testing.
- **NFR5.2:** Key logic, especially in `utils/sunoApi.ts` (once it targets a real API), should have good test coverage.
- **NFR5.3:** The existing `tests/checkEndpoints.ts` should be expanded or replaced by a proper test suite.

### NFR6: Security
- **NFR6.1:** Credentials must be handled securely as per n8n standards.
- **NFR6.2:** No sensitive information should be inadvertently logged (e.g., full tokens, passwords after initial use).