@royalti/syynk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,571 @@
+/**
+ * @fileoverview Type definitions for the Syynk SDK
+ *
+ * These types mirror the Syynk API responses and provide type safety
+ * for SDK consumers.
+ */
+/**
+ * Configuration options for the SyynkClient
+ */
+interface SyynkClientOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for the API (default: https://syynk.to) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retries for rate-limited requests (default: 3) */
+    maxRetries?: number;
+}
+/**
+ * Options for transcribing audio from a URL
+ */
+interface TranscribeOptions {
+    /** URL of the audio file to transcribe */
+    audioUrl: string;
+    /** ISO 639-1 language code (e.g., 'en', 'es', 'ja'). Auto-detected if not specified */
+    language?: string;
+    /** Optional name for the project */
+    projectName?: string;
+}
+/**
+ * Options for transcribing audio from a file upload
+ */
+interface TranscribeFileOptions {
+    /** ISO 639-1 language code (e.g., 'en', 'es', 'ja'). Auto-detected if not specified */
+    language?: string;
+    /** Custom filename (defaults to 'audio' with detected extension) */
+    filename?: string;
+    /** Optional name for the project */
+    projectName?: string;
+}
+/**
+ * Result of a transcription operation
+ */
+interface TranscribeResult {
+    /** Unique identifier for the created project */
+    projectId: string;
+    /** Detected or specified language code */
+    language: string;
+    /** Audio duration in seconds */
+    duration: number;
+    /** Transcribed segments with line-level timestamps */
+    segments: Segment[];
+    /** Individual words with word-level timestamps */
+    words: Word[];
+}
+/**
+ * A segment represents a line of lyrics or a subtitle block
+ * with start and end timestamps
+ */
+interface Segment {
+    /** Unique segment identifier */
+    id: string;
+    /** Start time in seconds */
+    startTime: number;
+    /** End time in seconds */
+    endTime: number;
+    /** Text content of the segment */
+    text: string;
+    /** Order within the project (0-indexed) */
+    sortOrder: number;
+    /** Optional speaker identifier for multi-speaker content */
+    speakerId?: string | null;
+    /** Transcription confidence score (0-1) */
+    confidence?: number | null;
+}
+/**
+ * A word with precise timestamp within a segment
+ */
+interface Word {
+    /** Unique word identifier */
+    id: string;
+    /** ID of the parent segment */
+    segmentId: string;
+    /** Start time in seconds */
+    startTime: number;
+    /** End time in seconds */
+    endTime: number;
+    /** The word text */
+    word: string;
+    /** Order within the segment (0-indexed) */
+    sortOrder: number;
+    /** Transcription confidence score (0-1) */
+    confidence?: number | null;
+}
+/**
+ * Supported export format identifiers
+ */
+type ExportFormat = 'lrc' | 'srt' | 'vtt' | 'ttml' | 'json' | 'txt';
+/**
+ * Options for exporting segments to a specific format
+ */
+interface ExportOptions {
+    /** Target export format */
+    format: ExportFormat;
+    /** Segments to export */
+    segments: Segment[];
+    /** Optional words for word-level timing (supported by TTML and JSON) */
+    words?: Word[];
+    /** Project name for metadata (appears in file headers) */
+    projectName?: string;
+}
+/**
+ * Result of an export operation
+ */
+interface ExportResult {
+    /** The formatted content as a string */
+    content: string;
+    /** Suggested filename for download */
+    filename: string;
+    /** MIME type for the content */
+    mimeType: string;
+    /** File extension (without dot) */
+    extension: string;
+}
+/**
+ * Information about a supported export format
+ */
+interface FormatInfo {
+    /** Format identifier */
+    id: ExportFormat;
+    /** Human-readable format name */
+    name: string;
+    /** Description of the format and its use cases */
+    description: string;
+    /** File extension (without dot) */
+    extension: string;
+    /** MIME type */
+    mimeType: string;
+    /** Whether this format supports word-level timing */
+    supportsWordTiming: boolean;
+}
+/**
+ * Project type identifier
+ */
+type ProjectType = 'lyricsync' | 'subsync';
+/**
+ * Project status
+ */
+type ProjectStatus = 'draft' | 'processing' | 'ready' | 'error';
+/**
+ * Options for listing projects
+ */
+interface ListProjectsOptions {
+    /** Maximum number of projects to return (default: 20, max: 100) */
+    limit?: number;
+    /** Number of projects to skip for pagination */
+    offset?: number;
+    /** Filter by project status */
+    status?: ProjectStatus;
+    /** Filter by project type */
+    type?: ProjectType;
+}
+/**
+ * Paginated result for project listing
+ */
+interface ProjectsResult {
+    /** Array of projects */
+    projects: Project[];
+    /** Total count of projects matching filters */
+    total: number;
+    /** Current limit */
+    limit: number;
+    /** Current offset */
+    offset: number;
+    /** Whether there are more results */
+    hasMore: boolean;
+}
+/**
+ * Options for getting a single project
+ */
+interface GetProjectOptions {
+    /** Include word-level timing data (default: true) */
+    includeWords?: boolean;
+    /** Include segments (default: true) */
+    includeSegments?: boolean;
+}
+/**
+ * A Syynk project containing synchronized content
+ */
+interface Project {
+    /** Unique project identifier */
+    id: string;
+    /** Project name/title */
+    name: string | null;
+    /** Project type */
+    type: ProjectType;
+    /** Current status */
+    status: ProjectStatus;
+    /** Audio/video duration in seconds */
+    durationSeconds: number | null;
+    /** URL to the audio file (if stored) */
+    audioUrl: string | null;
+    /** URL to the video file (for subsync projects) */
+    videoUrl: string | null;
+    /** Error message if status is 'error' */
+    errorMessage?: string | null;
+    /** ISO 8601 creation timestamp */
+    createdAt: string;
+    /** ISO 8601 last update timestamp */
+    updatedAt: string;
+}
+/**
+ * Full project result including segments and words
+ */
+interface ProjectResult extends Project {
+    /** Project segments (included by default) */
+    segments: Segment[];
+    /** Project words (included by default) */
+    words: Word[];
+}
+/**
+ * Rate limit information from API response headers
+ */
+interface RateLimitInfo {
+    /** Maximum requests allowed in the window */
+    limit: number;
+    /** Remaining requests in the current window */
+    remaining: number;
+    /** Unix timestamp when the rate limit resets */
+    reset: number;
+}
+/**
+ * Standard API response envelope
+ */
+interface ApiResponse<T> {
+    /** Response data */
+    data: T;
+    /** Optional metadata */
+    meta?: {
+        /** Rate limit information */
+        rateLimit?: RateLimitInfo;
+    };
+}
+/**
+ * API error response
+ */
+interface ApiErrorResponse {
+    /** Error information */
+    error: {
+        /** Error code */
+        code: string;
+        /** Human-readable error message */
+        message: string;
+        /** Additional error details */
+        details?: unknown;
+    };
+}
+
+/**
+ * @fileoverview Syynk API client implementation
+ *
+ * Provides a type-safe client for interacting with the Syynk API.
+ * Includes automatic retry with exponential backoff for rate-limited requests.
+ */
+
+/**
+ * Syynk API client for transcription and export operations
+ *
+ * @example
+ * ```typescript
+ * import { SyynkClient } from '@syynk/sdk';
+ *
+ * const client = new SyynkClient({ apiKey: 'your-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,
+ * });
+ * ```
+ */
+declare class SyynkClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    /** Last rate limit info received from the API */
+    private lastRateLimitInfo;
+    /**
+     * Create a new Syynk API client
+     *
+     * @param options - Client configuration options
+     * @throws {Error} If apiKey is not provided
+     */
+    constructor(options: SyynkClientOptions);
+    /**
+     * Get the current rate limit information
+     *
+     * @returns The last rate limit info received, or null if no requests have been made
+     */
+    getRateLimitInfo(): RateLimitInfo | null;
+    /**
+     * 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`);
+     * ```
+     */
+    transcribe(options: TranscribeOptions): Promise<TranscribeResult>;
+    /**
+     * 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' });
+     * ```
+     */
+    transcribeFile(file: Blob | ArrayBuffer | Uint8Array, options?: TranscribeFileOptions): Promise<TranscribeResult>;
+    /**
+     * 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);
+     * ```
+     */
+    export(options: ExportOptions): Promise<ExportResult>;
+    /**
+     * 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);
+     * ```
+     */
+    getFormats(): Promise<FormatInfo[]>;
+    /**
+     * 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`);
+     * ```
+     */
+    listProjects(options?: ListProjectsOptions): Promise<ProjectsResult>;
+    /**
+     * 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`);
+     * ```
+     */
+    getProject(id: string, options?: GetProjectOptions): Promise<ProjectResult>;
+    /**
+     * Delete a project by ID
+     *
+     * @param id - Project ID
+     *
+     * @example
+     * ```typescript
+     * await client.deleteProject('project-id');
+     * ```
+     */
+    deleteProject(id: string): Promise<void>;
+    /**
+     * Make an authenticated API request with automatic retry
+     *
+     * @param path - API path (starting with /)
+     * @param options - Fetch request options
+     * @returns Parsed response data
+     */
+    private request;
+    /**
+     * Parse rate limit headers from response
+     */
+    private parseRateLimitHeaders;
+    /**
+     * Handle error responses and convert to typed errors
+     */
+    private handleErrorResponse;
+    /**
+     * Calculate retry delay with exponential backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleep for the specified duration
+     */
+    private sleep;
+}
+
+/**
+ * @fileoverview Custom error classes for the Syynk SDK
+ *
+ * Provides typed errors for different API failure scenarios.
+ */
+/**
+ * Base error class for all Syynk SDK errors
+ */
+declare class SyynkError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** HTTP status code */
+    readonly status: number;
+    /** Additional error details from the API */
+    readonly details?: unknown;
+    constructor(message: string, code: string, status: number, details?: unknown);
+    /**
+     * Convert error to a plain object for serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication error (401)
+ *
+ * Thrown when the API key is missing, invalid, or expired.
+ */
+declare class AuthenticationError extends SyynkError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Authorization error (403)
+ *
+ * Thrown when the API key doesn't have permission for the requested operation.
+ */
+declare class AuthorizationError extends SyynkError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Rate limit error (429)
+ *
+ * Thrown when the API rate limit has been exceeded.
+ * Includes information about when the limit resets.
+ */
+declare class RateLimitError extends SyynkError {
+    /** Unix timestamp when the rate limit resets */
+    readonly resetAt: number;
+    /** Seconds until the rate limit resets */
+    readonly retryAfter: number;
+    constructor(message: string | undefined, resetAt: number, details?: unknown);
+    /**
+     * Get the Date object for when the rate limit resets
+     */
+    getResetDate(): Date;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Validation error (400)
+ *
+ * Thrown when the request contains invalid data.
+ */
+declare class ValidationError extends SyynkError {
+    /** Field-level validation errors */
+    readonly fieldErrors?: Record<string, string[]>;
+    constructor(message?: string, details?: unknown, fieldErrors?: Record<string, string[]>);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Not found error (404)
+ *
+ * Thrown when the requested resource doesn't exist.
+ */
+declare class NotFoundError extends SyynkError {
+    /** Type of resource that wasn't found */
+    readonly resourceType?: string;
+    /** ID of the resource that wasn't found */
+    readonly resourceId?: string;
+    constructor(message?: string, resourceType?: string, resourceId?: string, details?: unknown);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Server error (500+)
+ *
+ * Thrown when the server encounters an internal error.
+ */
+declare class ServerError extends SyynkError {
+    /** Request ID for debugging */
+    readonly requestId?: string;
+    constructor(message?: string, status?: number, requestId?: string, details?: unknown);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Network error
+ *
+ * Thrown when a network request fails (connection refused, timeout, etc.)
+ */
+declare class NetworkError extends SyynkError {
+    /** The original error that caused this network error */
+    readonly cause?: Error;
+    constructor(message?: string, cause?: Error);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Timeout error
+ *
+ * Thrown when a request times out.
+ */
+declare class TimeoutError extends SyynkError {
+    /** The timeout duration in milliseconds */
+    readonly timeoutMs: number;
+    constructor(message: string | undefined, timeoutMs: number);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Type guard to check if an error is a SyynkError
+ */
+declare function isSyynkError(error: unknown): error is SyynkError;
+/**
+ * Type guard to check if an error is a rate limit error
+ */
+declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Type guard to check if an error is retryable
+ */
+declare function isRetryableError(error: unknown): boolean;
+
+export { type ApiErrorResponse, type ApiResponse, AuthenticationError, AuthorizationError, type ExportFormat, type ExportOptions, type ExportResult, type FormatInfo, type GetProjectOptions, type ListProjectsOptions, NetworkError, NotFoundError, type Project, type ProjectResult, type ProjectStatus, type ProjectType, type ProjectsResult, RateLimitError, type RateLimitInfo, type Segment, ServerError, SyynkClient, type SyynkClientOptions, SyynkError, TimeoutError, type TranscribeFileOptions, type TranscribeOptions, type TranscribeResult, ValidationError, type Word, isRateLimitError, isRetryableError, isSyynkError };