@royalti/syynk 0.1.0

package/README.md

@@ -0,0 +1,279 @@
+# @royalti/syynk
+
+TypeScript SDK for the Syynk API - transcribe audio and export synchronized lyrics/subtitles.
+
+## Installation
+
+```bash
+npm install @royalti/syynk
+# or
+yarn add @royalti/syynk
+# or
+pnpm add @royalti/syynk
+```
+
+## Quick Start
+
+```typescript
+import { SyynkClient } from '@royalti/syynk';
+
+const client = new SyynkClient({
+  apiKey: process.env.SYYNK_API_KEY,
+});
+
+// Transcribe audio from URL
+const result = await client.transcribe({
+  audioUrl: 'https://example.com/song.mp3',
+  language: 'en',
+});
+
+// Export to LRC format
+const lrc = await client.export({
+  format: 'lrc',
+  segments: result.segments,
+  projectName: 'My Song',
+});
+
+console.log(lrc.content);
+```
+
+## Features
+
+- Transcribe audio from URL or file upload
+- Export to multiple formats: LRC, SRT, VTT, TTML, JSON, TXT
+- Full TypeScript support
+- Automatic retry with exponential backoff
+- Rate limit handling
+- Works in Node.js (18+) and browsers
+
+## API Reference
+
+### `SyynkClient`
+
+Create a new client instance:
+
+```typescript
+const client = new SyynkClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://syynk.to', // optional
+  timeout: 30000, // optional, in milliseconds
+  maxRetries: 3, // optional
+});
+```
+
+### Methods
+
+#### `transcribe(options)`
+
+Transcribe audio from a URL.
+
+```typescript
+const result = await client.transcribe({
+  audioUrl: 'https://example.com/song.mp3',
+  language: 'en', // optional, auto-detected if not specified
+  projectName: 'My Song', // optional
+});
+
+// Result contains:
+// - projectId: string
+// - language: string
+// - duration: number (seconds)
+// - segments: Segment[]
+// - words: Word[]
+```
+
+#### `transcribeFile(file, options?)`
+
+Transcribe audio from a file upload.
+
+```typescript
+// Node.js
+import fs from 'fs';
+
+const buffer = fs.readFileSync('song.mp3');
+const result = await client.transcribeFile(buffer, {
+  filename: 'song.mp3',
+  language: 'en',
+});
+
+// Browser
+const file = document.querySelector('input[type="file"]').files[0];
+const result = await client.transcribeFile(file);
+```
+
+#### `export(options)`
+
+Export segments to a specific format.
+
+```typescript
+const result = await client.export({
+  format: 'lrc', // 'lrc' | 'srt' | 'vtt' | 'ttml' | 'json' | 'txt'
+  segments: transcription.segments,
+  words: transcription.words, // optional, for word-level timing
+  projectName: 'My Song', // optional
+});
+
+// Result contains:
+// - content: string
+// - filename: string
+// - mimeType: string
+// - extension: string
+```
+
+#### `getFormats()`
+
+Get information about available export formats.
+
+```typescript
+const formats = await client.getFormats();
+
+// Returns:
+// [
+//   { id: 'lrc', name: 'LRC', supportsWordTiming: false, ... },
+//   { id: 'ttml', name: 'TTML', supportsWordTiming: true, ... },
+//   ...
+// ]
+```
+
+#### `listProjects(options?)`
+
+List your projects with optional filtering.
+
+```typescript
+const result = await client.listProjects({
+  status: 'ready',
+  type: 'lyricsync',
+  limit: 20,
+  offset: 0,
+});
+
+// Result contains:
+// - projects: Project[]
+// - total: number
+// - hasMore: boolean
+```
+
+#### `getProject(id, options?)`
+
+Get a single project with segments and words.
+
+```typescript
+const project = await client.getProject('project-id', {
+  includeWords: true,
+  includeSegments: true,
+});
+```
+
+#### `deleteProject(id)`
+
+Delete a project.
+
+```typescript
+await client.deleteProject('project-id');
+```
+
+#### `getRateLimitInfo()`
+
+Get the current rate limit status.
+
+```typescript
+const rateLimit = client.getRateLimitInfo();
+
+if (rateLimit) {
+  console.log(`${rateLimit.remaining}/${rateLimit.limit} requests remaining`);
+  console.log(`Resets at ${new Date(rateLimit.reset * 1000)}`);
+}
+```
+
+## Error Handling
+
+The SDK provides typed errors for different failure scenarios:
+
+```typescript
+import {
+  SyynkClient,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+  ServerError,
+  NetworkError,
+  TimeoutError,
+} from '@royalti/syynk';
+
+try {
+  const result = await client.transcribe({ audioUrl: 'invalid' });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // Invalid or missing API key (401)
+    console.log('Check your API key');
+  } else if (error instanceof RateLimitError) {
+    // Rate limit exceeded (429)
+    console.log(`Retry after ${error.retryAfter} seconds`);
+    console.log(`Reset time: ${error.getResetDate()}`);
+  } else if (error instanceof ValidationError) {
+    // Invalid request data (400)
+    console.log(error.fieldErrors);
+  } else if (error instanceof NotFoundError) {
+    // Resource not found (404)
+    console.log('Project not found');
+  } else if (error instanceof ServerError) {
+    // Server error (500+)
+    console.log(`Request ID: ${error.requestId}`);
+  } else if (error instanceof NetworkError) {
+    // Connection failed
+    console.log('Check your internet connection');
+  } else if (error instanceof TimeoutError) {
+    // Request timed out
+    console.log(`Timed out after ${error.timeoutMs}ms`);
+  }
+}
+```
+
+### Type Guards
+
+```typescript
+import { isSyynkError, isRateLimitError, isRetryableError } from '@royalti/syynk';
+
+if (isSyynkError(error)) {
+  console.log(error.code, error.status);
+}
+
+if (isRateLimitError(error)) {
+  console.log(error.retryAfter);
+}
+
+if (isRetryableError(error)) {
+  // Error is rate limit, network, timeout, or server error
+}
+```
+
+## Types
+
+All types are exported for TypeScript users:
+
+```typescript
+import type {
+  Segment,
+  Word,
+  Project,
+  ExportFormat,
+  TranscribeResult,
+  ExportResult,
+} from '@royalti/syynk';
+```
+
+## Export Formats
+
+| Format | Extension | Word Timing | Use Case |
+|--------|-----------|-------------|----------|
+| LRC | `.lrc` | No | Karaoke players |
+| SRT | `.srt` | No | Video subtitles (VLC, YouTube) |
+| VTT | `.vtt` | No | HTML5 `<track>` element |
+| TTML | `.ttml` | Yes | Professional broadcast |
+| JSON | `.json` | Yes | Developer integration |
+| TXT | `.txt` | No | Plain text lyrics |
+
+## License
+
+MIT