n8n-nodes-starter/interfaces/SunoTypes.ts

// interfaces/SunoTypes.ts

/**
 * Represents the authentication response from the Suno API.
 */
export interface SunoAuthResponse {
    /**
     * The session token or JWT.
     * @type {string}
     */
    token?: string;

    /**
     * Session cookie, if authentication is cookie-based.
     * @type {string}
     */
    cookie?: string;

    /**
     * The user ID, if provided by the authentication response.
     * @type {string}
     */
    userId?: string;

    /**
     * Error message, if authentication failed.
     * @type {string}
     */
    error?: string;
}

/**
 * Represents a job submitted to the Suno API, typically for song generation.
 */
export interface SunoJob {
    /**
     * Unique identifier for the job.
     * @type {string}
     */
    id: string;

    /**
     * Current status of the job.
     * @type {'queued' | 'processing' | 'generating' | 'complete' | 'failed'}
     */
    status: 'queued' | 'processing' | 'generating' | 'complete' | 'failed';

    /**
     * Identifier of the track that is/will be generated by this job.
     * Available when the job status is 'complete'.
     * @type {string}
     */
    trackId?: string;

    /**
     * Error message if the job failed.
     * @type {string}
     */
    error?: string;

    /**
     * Timestamp of when the job was created (ISO date string).
     * @type {string}
     */
    createdAt: string;

    /**
     * Progress of the job, typically a percentage (0-100).
     * @type {number}
     */
    progress?: number;

    /**
     * Any additional metadata associated with the job.
     * @type {Record<string, any>}
     */
    metadata?: Record<string, any>;
}

/**
 * Represents a music track generated by or stored in Suno AI.
 */
export interface SunoTrack {
    /**
     * Unique identifier for the track.
     * @type {string}
     */
    id: string;

    /**
     * Title of the track.
     * @type {string}
     */
    title?: string;

    /**
     * Artist name associated with the track.
     * @type {string}
     */
    artist?: string;

    /**
     * URL to the cover art or image associated with the track.
     * @type {string}
     */
    imageUrl?: string;

    /**
     * URL to the playable audio file or a preview.
     * @type {string}
     */
    audioUrl?: string;

    /**
     * Duration of the track in seconds.
     * @type {number}
     */
    duration?: number;

    /**
     * Current status of the track (distinct from job status, e.g., availability).
     * @type {'queued' | 'generating' | 'complete' | 'failed' | 'available'}
     */
    status: 'queued' | 'generating' | 'complete' | 'failed' | 'available'; // Added 'available'

    /**
     * Timestamp of when the track was created or made available (ISO date string).
     * @type {string}
     */
    createdAt?: string;

    /**
     * Indicates if the track is public or private.
     * @type {boolean}
     */
    isPublic?: boolean;

    /**
     * Any additional metadata associated with the track.
     * @type {Record<string, any>}
     */
    metadata?: Record<string, any>;
}

/**
 * Options for submitting a prompt to generate music.
 */
export interface SunoPromptOptions {
    /**
     * Desired musical style (e.g., 'pop', 'orchestral', 'jazz').
     * @type {string}
     */
    style?: string;

    /**
     * Desired mood for the music (e.g., 'happy', 'epic', 'chill').
     * @type {string}
     */
    mood?: string;

    /**
     * Whether the generated track should be instrumental.
     * @type {boolean}
     */
    instrumental?: boolean;

    /**
     * Flag for advanced 'custom mode' features, if available.
     * @type {boolean}
     */
    custom?: boolean;

    /**
     * ID of a reference track for voice or style transfer.
     * @type {string}
     */
    referenceTrackId?: string;

    /**
     * ID of a predefined voice to use for generation.
     * @type {string}
     */
    voiceId?: string;
}