beatlyze 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# beatlyze
+
+JavaScript/TypeScript SDK for the [Beatlyze](https://beatlyze.dev) audio analysis API.
+
+## Install
+
+```bash
+npm install beatlyze
+```
+
+## Quick start
+
+```javascript
+const { Beatlyze } = require("beatlyze");
+
+const bz = new Beatlyze("bz_your_api_key");
+
+// Analyze from URL (waits for result by default)
+const result = await bz.analyzeUrl("https://example.com/track.mp3");
+console.log(result.bpm);        // 128.4
+console.log(result.key);        // "A"
+console.log(result.energy);     // 0.78
+
+// Submit without waiting
+const job = await bz.analyzeUrl("https://example.com/track.mp3", { wait: false });
+console.log(job.job_id);
+
+// Check result later
+const analysis = await bz.getAnalysis(job.job_id);
+
+// Batch (up to 10 URLs)
+const jobs = await bz.analyzeBatch([
+  "https://example.com/a.mp3",
+  "https://example.com/b.mp3",
+]);
+
+// Check usage
+const usage = await bz.getUsage();
+console.log(`${usage.count}/${usage.limit} analyses used`);
+```
+
+## TypeScript
+
+Full type definitions included. Import types directly:
+
+```typescript
+import { Beatlyze, AnalysisResult, BeatlyzeError } from "beatlyze";
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "beatlyze",
+  "version": "0.1.0",
+  "description": "JavaScript/TypeScript SDK for the Beatlyze audio analysis API.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": ["src/"],
+  "keywords": ["audio", "music", "analysis", "bpm", "key", "beatlyze"],
+  "license": "MIT",
+  "homepage": "https://beatlyze.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mg0024/beatlyze-analyzer"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,78 @@
+export interface AnalysisResult {
+  bpm: number;
+  bpm_confidence?: number;
+  key: string;
+  scale: string;
+  key_notation: string;
+  key_confidence?: number;
+  energy: number;
+  danceability: number;
+  valence: number;
+  loudness_lufs: number;
+  mood_tags: string[];
+  genre_suggestions: string[];
+  duration_seconds: number;
+  time_signature?: number;
+  sections?: Array<{
+    start_time: number;
+    duration: number;
+    key: string;
+    loudness: number;
+    energy: number;
+  }>;
+}
+
+export interface JobStatus {
+  job_id: string;
+  status: "pending" | "processing" | "completed" | "failed";
+  result?: AnalysisResult;
+  error?: string;
+  created_at?: string;
+  completed_at?: string;
+}
+
+export interface UsageInfo {
+  month: string;
+  count: number;
+  limit: number;
+  tier: string;
+  remaining: number;
+}
+
+export interface AnalyzeOptions {
+  webhookUrl?: string;
+  wait?: boolean;
+  idempotencyKey?: string;
+}
+
+export interface GetAnalysisOptions {
+  full?: boolean;
+}
+
+export interface BatchOptions {
+  webhookUrl?: string;
+}
+
+export interface BeatlyzeOptions {
+  baseUrl?: string;
+  pollInterval?: number;
+  maxWait?: number;
+}
+
+export class BeatlyzeError extends Error {
+  statusCode: number;
+  detail: string;
+  constructor(statusCode: number, detail: string);
+}
+
+export class Beatlyze {
+  constructor(apiKey: string, options?: BeatlyzeOptions);
+  analyzeUrl(url: string, options?: AnalyzeOptions): Promise<AnalysisResult>;
+  analyzeUrl(
+    url: string,
+    options: AnalyzeOptions & { wait: false }
+  ): Promise<JobStatus>;
+  getAnalysis(jobId: string, options?: GetAnalysisOptions): Promise<JobStatus>;
+  getUsage(): Promise<UsageInfo>;
+  analyzeBatch(urls: string[], options?: BatchOptions): Promise<JobStatus[]>;
+}

package/src/index.js

@@ -0,0 +1,150 @@
+/**
+ * Beatlyze JavaScript SDK — audio analysis from any URL or file.
+ *
+ * @example
+ * const { Beatlyze } = require("beatlyze");
+ * const bz = new Beatlyze("bz_your_api_key");
+ * const result = await bz.analyzeUrl("https://example.com/track.mp3");
+ * console.log(result.bpm, result.key);
+ */
+
+class BeatlyzeError extends Error {
+  constructor(statusCode, detail) {
+    super(`HTTP ${statusCode}: ${detail}`);
+    this.name = "BeatlyzeError";
+    this.statusCode = statusCode;
+    this.detail = detail;
+  }
+}
+
+class Beatlyze {
+  /**
+   * @param {string} apiKey - Your Beatlyze API key (starts with "bz_").
+   * @param {object} [options]
+   * @param {string} [options.baseUrl="https://api.beatlyze.dev"]
+   * @param {number} [options.pollInterval=2000] - Polling interval in ms.
+   * @param {number} [options.maxWait=300000] - Max wait time in ms.
+   */
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.baseUrl = options.baseUrl || "https://api.beatlyze.dev";
+    this.pollInterval = options.pollInterval || 2000;
+    this.maxWait = options.maxWait || 300000;
+  }
+
+  async _request(method, path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = { "X-API-Key": this.apiKey, ...options.headers };
+
+    const fetchOptions = { method, headers };
+
+    if (options.json) {
+      headers["Content-Type"] = "application/json";
+      fetchOptions.body = JSON.stringify(options.json);
+    } else if (options.body) {
+      fetchOptions.body = options.body;
+    }
+
+    const resp = await fetch(url, fetchOptions);
+
+    if (!resp.ok) {
+      let detail;
+      try {
+        const body = await resp.json();
+        detail = body.detail || JSON.stringify(body);
+      } catch {
+        detail = await resp.text();
+      }
+      throw new BeatlyzeError(resp.status, detail);
+    }
+
+    return resp.json();
+  }
+
+  async _waitForResult(jobId) {
+    const start = Date.now();
+    while (true) {
+      const result = await this._request("GET", `/v1/analysis/${jobId}`);
+      if (result.status === "completed" || result.status === "failed") {
+        if (result.status === "failed") {
+          throw new BeatlyzeError(500, result.error || "Analysis failed");
+        }
+        return result.result || {};
+      }
+
+      if (Date.now() - start > this.maxWait) {
+        throw new BeatlyzeError(408, `Timed out waiting for job ${jobId}`);
+      }
+
+      await new Promise((r) => setTimeout(r, this.pollInterval));
+    }
+  }
+
+  /**
+   * Analyze audio from a URL.
+   *
+   * @param {string} url - Public URL to an audio file.
+   * @param {object} [options]
+   * @param {string} [options.webhookUrl] - URL to receive results via POST.
+   * @param {boolean} [options.wait=true] - Poll until complete.
+   * @param {string} [options.idempotencyKey] - Prevent duplicate submissions.
+   * @returns {Promise<object>} Analysis result or job status.
+   */
+  async analyzeUrl(url, options = {}) {
+    const body = { url };
+    if (options.webhookUrl) body.webhook_url = options.webhookUrl;
+
+    const headers = {};
+    if (options.idempotencyKey)
+      headers["Idempotency-Key"] = options.idempotencyKey;
+
+    const resp = await this._request("POST", "/v1/analyze/url", {
+      json: body,
+      headers,
+    });
+
+    if (options.wait === false) return resp;
+    return this._waitForResult(resp.job_id);
+  }
+
+  /**
+   * Get analysis result for a job.
+   *
+   * @param {string} jobId - The job UUID.
+   * @param {object} [options]
+   * @param {boolean} [options.full=false] - Include section-level detail.
+   * @returns {Promise<object>}
+   */
+  async getAnalysis(jobId, options = {}) {
+    const suffix = options.full ? "/full" : "";
+    return this._request("GET", `/v1/analysis/${jobId}${suffix}`);
+  }
+
+  /**
+   * Get current month's usage stats.
+   * @returns {Promise<object>} Usage data with month, count, limit, tier.
+   */
+  async getUsage() {
+    return this._request("GET", "/v1/usage");
+  }
+
+  /**
+   * Submit a batch of URLs for analysis (max 10).
+   *
+   * @param {string[]} urls - List of audio URLs.
+   * @param {object} [options]
+   * @param {string} [options.webhookUrl] - Webhook URL for all items.
+   * @returns {Promise<object[]>} List of job status objects.
+   */
+  async analyzeBatch(urls, options = {}) {
+    const items = urls.map((u) =>
+      options.webhookUrl ? { url: u, webhook_url: options.webhookUrl } : { url: u }
+    );
+    const resp = await this._request("POST", "/v1/batch", {
+      json: { items },
+    });
+    return resp.jobs || [];
+  }
+}
+
+module.exports = { Beatlyze, BeatlyzeError };