@thinkable-labs/music-generator 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { MusicGenerator } from "./suno-client";
+export type { MusicGeneratorConfig, SimpleGenerateRequest, AdvancedGenerateRequest, GenerateResponse, TaskInfo, TaskStatus, SongData, GenerationRecord, DownloadResult, CallbackType, CallbackPayload, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MusicGenerator = void 0;
+// ─── Client ─────────────────────────────────────────────────────────
+var suno_client_1 = require("./suno-client");
+Object.defineProperty(exports, "MusicGenerator", { enumerable: true, get: function () { return suno_client_1.MusicGenerator; } });
+//# sourceMappingURL=index.js.map

package/dist/suno-client.d.ts

@@ -0,0 +1,39 @@
+import type { MusicGeneratorConfig, SimpleGenerateRequest, AdvancedGenerateRequest, TaskInfo, SongData, GenerationRecord, DownloadResult } from "./types";
+export declare class MusicGenerator {
+    private apiKey;
+    private pollInterval;
+    private pollTimeout;
+    private history;
+    constructor(config: MusicGeneratorConfig);
+    /**
+     * Generate an instrumental song from a text description.
+     * Returns 2 songs. Polls until complete or timeout.
+     */
+    generateSimple(request: SimpleGenerateRequest): Promise<GenerationRecord>;
+    /**
+     * Generate a song with custom lyrics, style, and title.
+     * If lyrics is empty, generates an instrumental.
+     * Returns 2 songs. Polls until complete or timeout.
+     */
+    generateAdvanced(request: AdvancedGenerateRequest): Promise<GenerationRecord>;
+    /** Check the status of a generation task */
+    getTaskStatus(taskId: string): Promise<TaskInfo>;
+    /** Get all generation records from this session */
+    getHistory(): GenerationRecord[];
+    /** Clear session history */
+    clearHistory(): void;
+    /**
+     * Download a generated song to a local folder.
+     * @param song - The song to download
+     * @param outputDir - Target directory (must exist)
+     * @param filename - Optional custom filename (without extension)
+     */
+    downloadSong(song: SongData, outputDir: string, filename?: string): Promise<DownloadResult>;
+    private pollUntilComplete;
+    private post;
+    private get;
+    private handleResponse;
+    private downloadFile;
+    private sleep;
+}
+//# sourceMappingURL=suno-client.d.ts.map

package/dist/suno-client.js

@@ -0,0 +1,297 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MusicGenerator = void 0;
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const API_BASE = "https://api.sunoapi.org";
+const MODEL = "V5_5";
+const FAILED_STATUSES = [
+    "CREATE_TASK_FAILED",
+    "GENERATE_AUDIO_FAILED",
+    "CALLBACK_EXCEPTION",
+    "SENSITIVE_WORD_ERROR",
+];
+class MusicGenerator {
+    constructor(config) {
+        this.history = [];
+        if (!config.apiKey) {
+            throw new Error("API key is required");
+        }
+        this.apiKey = config.apiKey;
+        this.pollInterval = config.pollInterval ?? 5000;
+        this.pollTimeout = config.pollTimeout ?? 300000;
+    }
+    // ─── Simple Mode ────────────────────────────────────────────────
+    /**
+     * Generate an instrumental song from a text description.
+     * Returns 2 songs. Polls until complete or timeout.
+     */
+    async generateSimple(request) {
+        if (!request.prompt || request.prompt.trim().length === 0) {
+            throw new Error("Song description is required");
+        }
+        if (request.prompt.length > 500) {
+            throw new Error("Song description must be 500 characters or less");
+        }
+        const body = {
+            prompt: request.prompt,
+            customMode: false,
+            instrumental: true,
+            model: MODEL,
+            ...(request.callBackUrl && { callBackUrl: request.callBackUrl }),
+        };
+        const response = await this.post("/api/v1/generate", body);
+        const taskId = response.data.taskId;
+        const taskInfo = await this.pollUntilComplete(taskId);
+        const songs = taskInfo.data.response?.sunoData ?? [];
+        const record = {
+            taskId,
+            status: taskInfo.data.status,
+            mode: "simple",
+            prompt: request.prompt,
+            songs,
+            createdAt: new Date().toISOString(),
+        };
+        this.history.unshift(record);
+        return record;
+    }
+    // ─── Advanced Mode ──────────────────────────────────────────────
+    /**
+     * Generate a song with custom lyrics, style, and title.
+     * If lyrics is empty, generates an instrumental.
+     * Returns 2 songs. Polls until complete or timeout.
+     */
+    async generateAdvanced(request) {
+        if (!request.style || request.style.trim().length === 0) {
+            throw new Error("Style is required in advanced mode");
+        }
+        if (request.style.length > 1000) {
+            throw new Error("Style must be 1000 characters or less");
+        }
+        if (request.lyrics && request.lyrics.length > 3000) {
+            throw new Error("Lyrics must be 3000 characters or less");
+        }
+        if (request.title && request.title.length > 100) {
+            throw new Error("Title must be 100 characters or less");
+        }
+        const isInstrumental = !request.lyrics || request.lyrics.trim().length === 0;
+        const body = {
+            customMode: true,
+            instrumental: isInstrumental,
+            style: request.style,
+            model: MODEL,
+        };
+        if (!isInstrumental) {
+            body.prompt = request.lyrics;
+        }
+        if (request.title) {
+            body.title = request.title;
+        }
+        if (request.callBackUrl) {
+            body.callBackUrl = request.callBackUrl;
+        }
+        const response = await this.post("/api/v1/generate", body);
+        const taskId = response.data.taskId;
+        const taskInfo = await this.pollUntilComplete(taskId);
+        const songs = taskInfo.data.response?.sunoData ?? [];
+        const record = {
+            taskId,
+            status: taskInfo.data.status,
+            mode: "advanced",
+            prompt: isInstrumental ? `[instrumental] ${request.style}` : (request.lyrics ?? ""),
+            style: request.style,
+            title: request.title,
+            lyrics: request.lyrics,
+            songs,
+            createdAt: new Date().toISOString(),
+        };
+        this.history.unshift(record);
+        return record;
+    }
+    // ─── Task Status ────────────────────────────────────────────────
+    /** Check the status of a generation task */
+    async getTaskStatus(taskId) {
+        return this.get(`/api/v1/generate/record-info?taskId=${taskId}`);
+    }
+    // ─── History ────────────────────────────────────────────────────
+    /** Get all generation records from this session */
+    getHistory() {
+        return [...this.history];
+    }
+    /** Clear session history */
+    clearHistory() {
+        this.history = [];
+    }
+    // ─── Download ───────────────────────────────────────────────────
+    /**
+     * Download a generated song to a local folder.
+     * @param song - The song to download
+     * @param outputDir - Target directory (must exist)
+     * @param filename - Optional custom filename (without extension)
+     */
+    async downloadSong(song, outputDir, filename) {
+        if (!outputDir || outputDir.trim().length === 0) {
+            return { success: false, error: "Please select a download folder" };
+        }
+        if (!fs.existsSync(outputDir)) {
+            return { success: false, error: `Folder does not exist: ${outputDir}` };
+        }
+        if (!song.audioUrl) {
+            return { success: false, error: "Song has no download URL yet" };
+        }
+        const safeName = filename
+            ? filename.replace(/[^a-zA-Z0-9_\-\s]/g, "")
+            : (song.title || `suno-${song.id}`).replace(/[^a-zA-Z0-9_\-\s]/g, "");
+        const filePath = path.join(outputDir, `${safeName}.mp3`);
+        try {
+            await this.downloadFile(song.audioUrl, filePath);
+            return { success: true, filePath };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { success: false, error: `Download failed: ${message}` };
+        }
+    }
+    // ─── Polling ────────────────────────────────────────────────────
+    async pollUntilComplete(taskId) {
+        const start = Date.now();
+        while (Date.now() - start < this.pollTimeout) {
+            const info = await this.getTaskStatus(taskId);
+            const status = info.data.status;
+            if (status === "SUCCESS") {
+                return info;
+            }
+            if (FAILED_STATUSES.includes(status)) {
+                throw new Error(`Generation failed: ${status}${info.data.errorMessage ? ` — ${info.data.errorMessage}` : ""}`);
+            }
+            await this.sleep(this.pollInterval);
+        }
+        throw new Error(`Generation timed out after ${this.pollTimeout / 1000}s`);
+    }
+    // ─── HTTP Helpers ───────────────────────────────────────────────
+    async post(endpoint, body) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(endpoint, API_BASE);
+            const data = JSON.stringify(body);
+            const req = https.request({
+                hostname: url.hostname,
+                port: url.port || 443,
+                path: url.pathname,
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Content-Length": Buffer.byteLength(data),
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+            }, (res) => this.handleResponse(res, resolve, reject));
+            req.on("error", reject);
+            req.write(data);
+            req.end();
+        });
+    }
+    async get(endpoint) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(endpoint, API_BASE);
+            const req = https.request({
+                hostname: url.hostname,
+                port: url.port || 443,
+                path: `${url.pathname}${url.search}`,
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+            }, (res) => this.handleResponse(res, resolve, reject));
+            req.on("error", reject);
+            req.end();
+        });
+    }
+    handleResponse(res, resolve, reject) {
+        let body = "";
+        res.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        res.on("end", () => {
+            try {
+                const parsed = JSON.parse(body);
+                if (parsed.code && parsed.code !== 200) {
+                    reject(new Error(`API error ${parsed.code}: ${parsed.msg || body}`));
+                }
+                else {
+                    resolve(parsed);
+                }
+            }
+            catch {
+                reject(new Error(`Failed to parse API response: ${body.substring(0, 200)}`));
+            }
+        });
+    }
+    async downloadFile(url, filePath) {
+        return new Promise((resolve, reject) => {
+            const parsedUrl = new URL(url);
+            const client = parsedUrl.protocol === "https:" ? https : http;
+            client.get(url, (res) => {
+                if (res.statusCode === 301 || res.statusCode === 302) {
+                    const redirectUrl = res.headers.location;
+                    if (redirectUrl) {
+                        this.downloadFile(redirectUrl, filePath).then(resolve).catch(reject);
+                        return;
+                    }
+                }
+                if (res.statusCode !== 200) {
+                    reject(new Error(`HTTP ${res.statusCode} downloading file`));
+                    return;
+                }
+                const fileStream = fs.createWriteStream(filePath);
+                res.pipe(fileStream);
+                fileStream.on("finish", () => {
+                    fileStream.close();
+                    resolve();
+                });
+                fileStream.on("error", (err) => {
+                    fs.unlink(filePath, () => { }); // clean up partial file
+                    reject(err);
+                });
+            }).on("error", reject);
+        });
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.MusicGenerator = MusicGenerator;
+//# sourceMappingURL=suno-client.js.map

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/** Simple mode: just a text description, always instrumental */
+export interface SimpleGenerateRequest {
+    /** Plain text description of the song (max 500 chars) */
+    prompt: string;
+    /** Webhook URL for completion notifications */
+    callBackUrl?: string;
+}
+/** Advanced mode: lyrics, style, and optional title */
+export interface AdvancedGenerateRequest {
+    /** Lyrics for the song (max 3000 chars). Leave empty for instrumental. */
+    lyrics?: string;
+    /** Music style/genre tags (max 1000 chars) e.g. "broken beats, unplugged, funky guitar riffs" */
+    style: string;
+    /** Song title (max 100 chars, optional) */
+    title?: string;
+    /** Webhook URL for completion notifications */
+    callBackUrl?: string;
+}
+export interface GenerateResponse {
+    code: number;
+    msg: string;
+    data: {
+        taskId: string;
+    };
+}
+export interface SongData {
+    id: string;
+    audioUrl: string;
+    streamAudioUrl: string;
+    imageUrl: string;
+    prompt: string;
+    title: string;
+    tags: string;
+    duration: number;
+    createTime: string;
+}
+export type TaskStatus = "PENDING" | "TEXT_SUCCESS" | "FIRST_SUCCESS" | "SUCCESS" | "CREATE_TASK_FAILED" | "GENERATE_AUDIO_FAILED" | "CALLBACK_EXCEPTION" | "SENSITIVE_WORD_ERROR";
+export interface TaskInfo {
+    code: number;
+    msg: string;
+    data: {
+        taskId: string;
+        status: TaskStatus;
+        operationType: string;
+        response: {
+            sunoData: SongData[];
+        } | null;
+        errorCode: string | null;
+        errorMessage: string | null;
+    };
+}
+export type CallbackType = "text" | "first" | "complete";
+export interface CallbackPayload {
+    type: CallbackType;
+    taskId: string;
+    data: SongData[];
+}
+export interface GenerationRecord {
+    taskId: string;
+    status: TaskStatus;
+    mode: "simple" | "advanced";
+    prompt: string;
+    style?: string;
+    title?: string;
+    lyrics?: string;
+    songs: SongData[];
+    createdAt: string;
+}
+export interface DownloadResult {
+    success: boolean;
+    filePath?: string;
+    error?: string;
+}
+export interface MusicGeneratorConfig {
+    /** Suno API key (provided by desktop app) */
+    apiKey: string;
+    /** Polling interval in ms when waiting for generation (default: 5000) */
+    pollInterval?: number;
+    /** Max polling time in ms before giving up (default: 300000 = 5 min) */
+    pollTimeout?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// ─── Generation Request Types ───────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@thinkable-labs/music-generator",
+  "version": "1.0.0",
+  "description": "Suno AI music generation wrapper for Thinkable Labs desktop app",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  }
+}