@royalti/syynk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,548 @@
+// src/errors.ts
+var SyynkError = class extends Error {
+  /** Error code for programmatic handling */
+  code;
+  /** HTTP status code */
+  status;
+  /** Additional error details from the API */
+  details;
+  constructor(message, code, status, details) {
+    super(message);
+    this.name = "SyynkError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Convert error to a plain object for serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      status: this.status,
+      details: this.details
+    };
+  }
+};
+var AuthenticationError = class extends SyynkError {
+  constructor(message = "Invalid or missing API key", details) {
+    super(message, "AUTHENTICATION_ERROR", 401, details);
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends SyynkError {
+  constructor(message = "Insufficient permissions for this operation", details) {
+    super(message, "AUTHORIZATION_ERROR", 403, details);
+    this.name = "AuthorizationError";
+  }
+};
+var RateLimitError = class extends SyynkError {
+  /** Unix timestamp when the rate limit resets */
+  resetAt;
+  /** Seconds until the rate limit resets */
+  retryAfter;
+  constructor(message = "Rate limit exceeded", resetAt, details) {
+    super(message, "RATE_LIMIT_ERROR", 429, details);
+    this.name = "RateLimitError";
+    this.resetAt = resetAt;
+    this.retryAfter = Math.max(0, Math.ceil(resetAt - Date.now() / 1e3));
+  }
+  /**
+   * Get the Date object for when the rate limit resets
+   */
+  getResetDate() {
+    return new Date(this.resetAt * 1e3);
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      resetAt: this.resetAt,
+      retryAfter: this.retryAfter
+    };
+  }
+};
+var ValidationError = class extends SyynkError {
+  /** Field-level validation errors */
+  fieldErrors;
+  constructor(message = "Invalid request data", details, fieldErrors) {
+    super(message, "VALIDATION_ERROR", 400, details);
+    this.name = "ValidationError";
+    this.fieldErrors = fieldErrors;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      fieldErrors: this.fieldErrors
+    };
+  }
+};
+var NotFoundError = class extends SyynkError {
+  /** Type of resource that wasn't found */
+  resourceType;
+  /** ID of the resource that wasn't found */
+  resourceId;
+  constructor(message = "Resource not found", resourceType, resourceId, details) {
+    super(message, "NOT_FOUND_ERROR", 404, details);
+    this.name = "NotFoundError";
+    this.resourceType = resourceType;
+    this.resourceId = resourceId;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      resourceType: this.resourceType,
+      resourceId: this.resourceId
+    };
+  }
+};
+var ServerError = class extends SyynkError {
+  /** Request ID for debugging */
+  requestId;
+  constructor(message = "Internal server error", status = 500, requestId, details) {
+    super(message, "SERVER_ERROR", status, details);
+    this.name = "ServerError";
+    this.requestId = requestId;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      requestId: this.requestId
+    };
+  }
+};
+var NetworkError = class extends SyynkError {
+  /** The original error that caused this network error */
+  cause;
+  constructor(message = "Network request failed", cause) {
+    super(message, "NETWORK_ERROR", 0);
+    this.name = "NetworkError";
+    this.cause = cause;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      cause: this.cause?.message
+    };
+  }
+};
+var TimeoutError = class extends SyynkError {
+  /** The timeout duration in milliseconds */
+  timeoutMs;
+  constructor(message = "Request timed out", timeoutMs) {
+    super(message, "TIMEOUT_ERROR", 0);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      timeoutMs: this.timeoutMs
+    };
+  }
+};
+function isSyynkError(error) {
+  return error instanceof SyynkError;
+}
+function isRateLimitError(error) {
+  return error instanceof RateLimitError;
+}
+function isRetryableError(error) {
+  if (error instanceof RateLimitError) return true;
+  if (error instanceof NetworkError) return true;
+  if (error instanceof TimeoutError) return true;
+  if (error instanceof ServerError && error.status >= 500) return true;
+  return false;
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://syynk.to";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var INITIAL_RETRY_DELAY = 1e3;
+var SyynkClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  maxRetries;
+  /** Last rate limit info received from the API */
+  lastRateLimitInfo = null;
+  /**
+   * Create a new Syynk API client
+   *
+   * @param options - Client configuration options
+   * @throws {Error} If apiKey is not provided
+   */
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  }
+  /**
+   * Get the current rate limit information
+   *
+   * @returns The last rate limit info received, or null if no requests have been made
+   */
+  getRateLimitInfo() {
+    return this.lastRateLimitInfo;
+  }
+  /**
+   * Transcribe audio from a URL
+   *
+   * @param options - Transcription options
+   * @returns Transcription result with segments and words
+   *
+   * @example
+   * ```typescript
+   * const result = await client.transcribe({
+   *   audioUrl: 'https://example.com/song.mp3',
+   *   language: 'en',
+   * });
+   * console.log(`Transcribed ${result.segments.length} segments`);
+   * ```
+   */
+  async transcribe(options) {
+    return this.request("/api/v1/transcribe", {
+      method: "POST",
+      body: JSON.stringify({
+        audioUrl: options.audioUrl,
+        language: options.language,
+        projectName: options.projectName
+      })
+    });
+  }
+  /**
+   * Transcribe audio from a file upload
+   *
+   * Works in both Node.js and browser environments.
+   *
+   * @param file - Audio file as Blob/File (browser) or ArrayBuffer/Uint8Array (Node.js Buffer works as it extends Uint8Array)
+   * @param options - Optional transcription options
+   * @returns Transcription result with segments and words
+   *
+   * @example
+   * ```typescript
+   * // Browser
+   * const file = document.querySelector('input[type="file"]').files[0];
+   * const result = await client.transcribeFile(file);
+   *
+   * // Node.js
+   * const buffer = fs.readFileSync('song.mp3');
+   * const result = await client.transcribeFile(buffer, { filename: 'song.mp3' });
+   * ```
+   */
+  async transcribeFile(file, options) {
+    const formData = new FormData();
+    const filename = options?.filename ?? (file instanceof Blob && "name" in file ? file.name : null) ?? "audio";
+    if (file instanceof Blob) {
+      formData.append("file", file, filename);
+    } else {
+      const blob = new Blob([file]);
+      formData.append("file", blob, filename);
+    }
+    if (options?.language) {
+      formData.append("language", options.language);
+    }
+    if (options?.projectName) {
+      formData.append("projectName", options.projectName);
+    }
+    return this.request("/api/v1/transcribe/upload", {
+      method: "POST",
+      body: formData
+      // Don't set Content-Type header - let the browser set it with boundary
+    });
+  }
+  /**
+   * Export segments to a specific format
+   *
+   * @param options - Export options including format and segments
+   * @returns Export result with content and metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await client.export({
+   *   format: 'lrc',
+   *   segments: transcription.segments,
+   *   projectName: 'My Song',
+   * });
+   *
+   * // Save the file
+   * fs.writeFileSync(`output.${result.extension}`, result.content);
+   * ```
+   */
+  async export(options) {
+    return this.request("/api/v1/export", {
+      method: "POST",
+      body: JSON.stringify({
+        format: options.format,
+        segments: options.segments,
+        words: options.words,
+        projectName: options.projectName
+      })
+    });
+  }
+  /**
+   * Get information about all available export formats
+   *
+   * @returns Array of format information objects
+   *
+   * @example
+   * ```typescript
+   * const formats = await client.getFormats();
+   * const wordTimingFormats = formats.filter(f => f.supportsWordTiming);
+   * ```
+   */
+  async getFormats() {
+    return this.request("/api/v1/formats", {
+      method: "GET"
+    });
+  }
+  /**
+   * List projects with optional filtering and pagination
+   *
+   * @param options - Listing options
+   * @returns Paginated list of projects
+   *
+   * @example
+   * ```typescript
+   * const result = await client.listProjects({
+   *   status: 'ready',
+   *   limit: 10,
+   * });
+   * console.log(`Found ${result.total} projects`);
+   * ```
+   */
+  async listProjects(options) {
+    const params = new URLSearchParams();
+    if (options?.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options?.offset !== void 0) {
+      params.set("offset", String(options.offset));
+    }
+    if (options?.status) {
+      params.set("status", options.status);
+    }
+    if (options?.type) {
+      params.set("type", options.type);
+    }
+    const queryString = params.toString();
+    const path = queryString ? `/api/v1/projects?${queryString}` : "/api/v1/projects";
+    return this.request(path, {
+      method: "GET"
+    });
+  }
+  /**
+   * Get a single project by ID
+   *
+   * @param id - Project ID
+   * @param options - Options for including segments/words
+   * @returns Project with segments and words
+   *
+   * @example
+   * ```typescript
+   * const project = await client.getProject('project-id', {
+   *   includeWords: true,
+   * });
+   * console.log(`Project has ${project.segments.length} segments`);
+   * ```
+   */
+  async getProject(id, options) {
+    const params = new URLSearchParams();
+    if (options?.includeWords !== void 0) {
+      params.set("includeWords", String(options.includeWords));
+    }
+    if (options?.includeSegments !== void 0) {
+      params.set("includeSegments", String(options.includeSegments));
+    }
+    const queryString = params.toString();
+    const path = queryString ? `/api/v1/projects/${id}?${queryString}` : `/api/v1/projects/${id}`;
+    return this.request(path, {
+      method: "GET"
+    });
+  }
+  /**
+   * Delete a project by ID
+   *
+   * @param id - Project ID
+   *
+   * @example
+   * ```typescript
+   * await client.deleteProject('project-id');
+   * ```
+   */
+  async deleteProject(id) {
+    await this.request(`/api/v1/projects/${id}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Make an authenticated API request with automatic retry
+   *
+   * @param path - API path (starting with /)
+   * @param options - Fetch request options
+   * @returns Parsed response data
+   */
+  async request(path, options, retryCount = 0) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json"
+    };
+    if (!(options.body instanceof FormData)) {
+      headers["Content-Type"] = "application/json";
+    }
+    const requestHeaders = {
+      ...headers,
+      ...options.headers
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers: requestHeaders,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      this.parseRateLimitHeaders(response.headers);
+      if (response.ok) {
+        if (response.status === 204 || response.headers.get("content-length") === "0") {
+          return void 0;
+        }
+        const json = await response.json();
+        if (json && typeof json === "object" && "data" in json) {
+          return json.data;
+        }
+        return json;
+      }
+      const error = await this.handleErrorResponse(response);
+      if (isRetryableError(error) && retryCount < this.maxRetries) {
+        const delay = this.calculateRetryDelay(error, retryCount);
+        await this.sleep(delay);
+        return this.request(path, options, retryCount + 1);
+      }
+      throw error;
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError") {
+        const timeoutError = new TimeoutError(
+          `Request timed out after ${this.timeout}ms`,
+          this.timeout
+        );
+        if (retryCount < this.maxRetries) {
+          const delay = this.calculateRetryDelay(timeoutError, retryCount);
+          await this.sleep(delay);
+          return this.request(path, options, retryCount + 1);
+        }
+        throw timeoutError;
+      }
+      if (err instanceof TypeError && err.message.includes("fetch")) {
+        const networkError = new NetworkError("Network request failed", err);
+        if (retryCount < this.maxRetries) {
+          const delay = this.calculateRetryDelay(networkError, retryCount);
+          await this.sleep(delay);
+          return this.request(path, options, retryCount + 1);
+        }
+        throw networkError;
+      }
+      if (err instanceof SyynkError) {
+        throw err;
+      }
+      throw new NetworkError(
+        err instanceof Error ? err.message : "Unknown error occurred",
+        err instanceof Error ? err : void 0
+      );
+    }
+  }
+  /**
+   * Parse rate limit headers from response
+   */
+  parseRateLimitHeaders(headers) {
+    const limit = headers.get("X-RateLimit-Limit");
+    const remaining = headers.get("X-RateLimit-Remaining");
+    const reset = headers.get("X-RateLimit-Reset");
+    if (limit && remaining && reset) {
+      this.lastRateLimitInfo = {
+        limit: parseInt(limit, 10),
+        remaining: parseInt(remaining, 10),
+        reset: parseInt(reset, 10)
+      };
+    }
+  }
+  /**
+   * Handle error responses and convert to typed errors
+   */
+  async handleErrorResponse(response) {
+    let errorData = null;
+    try {
+      errorData = await response.json();
+    } catch {
+    }
+    const message = errorData?.error?.message ?? response.statusText;
+    const code = errorData?.error?.code ?? "UNKNOWN_ERROR";
+    const details = errorData?.error?.details;
+    switch (response.status) {
+      case 400:
+        return new ValidationError(message, details);
+      case 401:
+        return new AuthenticationError(message, details);
+      case 403:
+        return new AuthorizationError(message, details);
+      case 404:
+        return new NotFoundError(message, void 0, void 0, details);
+      case 429: {
+        const resetHeader = response.headers.get("X-RateLimit-Reset");
+        const resetAt = resetHeader ? parseInt(resetHeader, 10) : Math.floor(Date.now() / 1e3) + 60;
+        return new RateLimitError(message, resetAt, details);
+      }
+      default:
+        if (response.status >= 500) {
+          const requestId = response.headers.get("X-Request-Id") ?? void 0;
+          return new ServerError(message, response.status, requestId, details);
+        }
+        return new SyynkError(message, code, response.status, details);
+    }
+  }
+  /**
+   * Calculate retry delay with exponential backoff
+   */
+  calculateRetryDelay(error, retryCount) {
+    if (error instanceof RateLimitError && error.retryAfter > 0) {
+      const jitter2 = Math.random() * 1e3;
+      return error.retryAfter * 1e3 + jitter2;
+    }
+    const baseDelay = INITIAL_RETRY_DELAY * Math.pow(2, retryCount);
+    const jitter = Math.random() * baseDelay * 0.25;
+    return Math.min(baseDelay + jitter, 3e4);
+  }
+  /**
+   * Sleep for the specified duration
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+export {
+  AuthenticationError,
+  AuthorizationError,
+  NetworkError,
+  NotFoundError,
+  RateLimitError,
+  ServerError,
+  SyynkClient,
+  SyynkError,
+  TimeoutError,
+  ValidationError,
+  isRateLimitError,
+  isRetryableError,
+  isSyynkError
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@royalti/syynk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Syynk API - transcribe audio and export synchronized lyrics/subtitles",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "syynk",
+    "api",
+    "transcription",
+    "lyrics",
+    "karaoke",
+    "subtitles",
+    "lrc",
+    "srt",
+    "vtt",
+    "whisper"
+  ],
+  "author": "Syynk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Royalti-io/syynk-to"
+  },
+  "homepage": "https://syynk.to/docs",
+  "bugs": {
+    "url": "https://github.com/Royalti-io/syynk-to/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}