subformer 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,403 @@
+/**
+ * Type definitions for Subformer SDK
+ */
+/** Job execution state */
+type JobState = "queued" | "active" | "completed" | "failed" | "cancelled";
+/** Type of background job */
+type JobType = "video-dubbing" | "voice-cloning" | "voice-synthesis" | "dub-studio-render-video";
+/** Source type for dubbing jobs */
+type DubSource = "youtube" | "tiktok" | "instagram" | "facebook" | "x" | "url";
+/** Supported languages for dubbing */
+type Language = "af-ZA" | "ar-SA" | "az-AZ" | "be-BY" | "bg-BG" | "bn-IN" | "bs-BA" | "ca-ES" | "cs-CZ" | "cy-GB" | "da-DK" | "de-DE" | "el-GR" | "en-US" | "es-ES" | "et-EE" | "fa-IR" | "fi-FI" | "fil-PH" | "fr-FR" | "gl-ES" | "gu-IN" | "he-IL" | "hi-IN" | "hr-HR" | "hu-HU" | "hy-AM" | "id-ID" | "is-IS" | "it-IT" | "ja-JP" | "jv-ID" | "ka-GE" | "kk-KZ" | "km-KH" | "kn-IN" | "ko-KR" | "la-VA" | "lt-LT" | "lv-LV" | "mk-MK" | "ml-IN" | "mn-MN" | "mr-IN" | "ms-MY" | "mt-MT" | "my-MM" | "nl-NL" | "no-NO" | "pa-IN" | "pl-PL" | "pt-BR" | "ro-RO" | "ru-RU" | "sk-SK" | "sl-SI" | "sq-AL" | "sr-RS" | "sv-SE" | "sw-KE" | "ta-IN" | "te-IN" | "th-TH" | "tl-PH" | "tr-TR" | "uk-UA" | "ur-PK" | "uz-UZ" | "vi-VN" | "zh-CN" | "zh-TW";
+/** Progress information for a job */
+interface JobProgress {
+    /** Progress percentage (0-100) */
+    progress: number;
+    /** Current status message */
+    message?: string;
+    /** Current processing step */
+    step?: string;
+}
+/** Metadata for a job */
+interface JobMetadata {
+    title?: string;
+    thumbnailUrl?: string;
+    duration?: number;
+    sourceUrl?: string;
+    sourceType?: string;
+    originalLanguage?: string;
+}
+/** A background job */
+interface Job {
+    id: string;
+    type: JobType;
+    userId: string;
+    state: JobState;
+    input?: unknown;
+    output?: unknown;
+    metadata?: JobMetadata | null;
+    createdAt: Date;
+    progress?: JobProgress | null;
+    processedOn?: Date | null;
+    finishedOn?: Date | null;
+    creditUsed?: number | null;
+}
+/** A saved voice in the voice library */
+interface Voice {
+    id: string;
+    name: string;
+    audioUrl: string;
+    gender: "male" | "female";
+    duration: number;
+    createdAt: Date;
+}
+/** Target voice using a preset */
+interface PresetVoice {
+    mode: "preset";
+    presetVoiceId: string;
+}
+/** Target voice using an uploaded audio file */
+interface UploadedVoice {
+    mode: "upload";
+    targetAudioUrl: string;
+}
+/** Target voice for cloning or synthesis */
+type TargetVoice = PresetVoice | UploadedVoice;
+/** Paginated list of jobs */
+interface PaginatedJobs {
+    data: Job[];
+    total: number;
+}
+/** Options for creating a dubbing job */
+interface DubOptions {
+    /** Source type */
+    source: DubSource;
+    /** URL of the video to dub */
+    url: string;
+    /** Target language for dubbing */
+    language: Language | string;
+    /** Disable watermark (requires paid plan) */
+    disableWatermark?: boolean;
+}
+/** Options for listing jobs */
+interface ListJobsOptions {
+    /** Number of items to skip */
+    offset?: number;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Filter by job type */
+    type?: JobType;
+}
+/** Options for waiting on a job */
+interface WaitForJobOptions {
+    /** Seconds between status checks */
+    pollInterval?: number;
+    /** Maximum seconds to wait (undefined for no timeout) */
+    timeout?: number;
+}
+/** Options for voice cloning */
+interface CloneVoiceOptions {
+    /** URL of the source audio to transform */
+    sourceAudioUrl: string;
+    /** Target voice (preset or uploaded) */
+    targetVoice: TargetVoice;
+}
+/** Options for voice synthesis */
+interface SynthesizeVoiceOptions {
+    /** Text to synthesize */
+    text: string;
+    /** Target voice (preset or uploaded) */
+    targetVoice: TargetVoice;
+}
+/** Options for creating a voice */
+interface CreateVoiceOptions {
+    /** Voice name */
+    name: string;
+    /** URL of the voice audio sample */
+    audioUrl: string;
+    /** Voice gender */
+    gender: "male" | "female";
+    /** Duration of audio sample in milliseconds */
+    duration: number;
+}
+/** Options for updating a voice */
+interface UpdateVoiceOptions {
+    /** Voice ID */
+    voiceId: string;
+    /** New voice name */
+    name?: string;
+    /** New voice gender */
+    gender?: "male" | "female";
+}
+/** Options for generating a voice upload URL */
+interface GenerateVoiceUploadUrlOptions {
+    /** Name of the file to upload */
+    fileName: string;
+    /** MIME type of the file */
+    contentType: string;
+}
+/** Presigned upload URL response */
+interface UploadUrl {
+    uploadUrl: string;
+    fileUrl: string;
+    key: string;
+}
+/** Usage data for active subscription */
+interface UsageData {
+    usedCredits: number;
+    planCredits: number;
+    totalEvents: number;
+    currentPlan: string;
+    periodStart: Date;
+    periodEnd: Date;
+}
+/** Current billing usage */
+interface Usage {
+    type: string;
+    data: UsageData;
+}
+/** Daily usage statistics */
+interface DailyUsage {
+    date: string;
+    "video-dubbing": number;
+    "voice-cloning": number;
+    "voice-synthesis": number;
+    "dub-studio-render-video": number;
+}
+/** User profile information */
+interface User {
+    id: string;
+    name?: string | null;
+    email: string;
+    emailVerified: boolean;
+    image?: string | null;
+    preferredTargetLanguage?: string | null;
+}
+/** Rate limit status */
+interface RateLimit {
+    remaining: number;
+    limit: number;
+    reset: number;
+    bucket: string;
+}
+/** Options for updating user profile */
+interface UpdateUserOptions {
+    /** New name */
+    name: string;
+    /** New email */
+    email: string;
+}
+
+/**
+ * Subformer API client
+ */
+
+interface SubformerOptions {
+    /** Your Subformer API key */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.subformer.com/v1) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Subformer API client for video dubbing, voice cloning, and text-to-speech.
+ *
+ * @example
+ * ```typescript
+ * import { Subformer } from 'subformer';
+ *
+ * const client = new Subformer({ apiKey: 'sk_subformer_...' });
+ *
+ * // Create a dubbing job
+ * const job = await client.dub({
+ *   source: 'youtube',
+ *   url: 'https://youtube.com/watch?v=VIDEO_ID',
+ *   language: 'es-ES'
+ * });
+ *
+ * // Wait for completion
+ * const result = await client.waitForJob(job.id);
+ * console.log('Done!', result.output);
+ * ```
+ */
+declare class Subformer {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options: SubformerOptions);
+    private request;
+    private handleError;
+    private transformDates;
+    /**
+     * Create a video dubbing job.
+     *
+     * @param options - Dubbing options
+     * @returns The created job
+     *
+     * @example
+     * ```typescript
+     * const job = await client.dub({
+     *   source: 'youtube',
+     *   url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
+     *   language: 'es-ES'
+     * });
+     * ```
+     */
+    dub(options: DubOptions): Promise<Job>;
+    /**
+     * Get list of supported languages for dubbing.
+     *
+     * @returns List of language codes
+     */
+    getLanguages(): Promise<Language[]>;
+    /**
+     * Get a job by ID.
+     *
+     * @param jobId - The job ID
+     * @returns The job
+     */
+    getJob(jobId: string): Promise<Job>;
+    /**
+     * List jobs for the authenticated user.
+     *
+     * @param options - List options
+     * @returns Paginated list of jobs
+     */
+    listJobs(options?: ListJobsOptions): Promise<PaginatedJobs>;
+    /**
+     * Delete jobs by IDs.
+     *
+     * @param jobIds - List of job IDs to delete (max 50)
+     * @returns True if successful
+     */
+    deleteJobs(jobIds: string[]): Promise<boolean>;
+    /**
+     * Wait for a job to complete.
+     *
+     * @param jobId - The job ID
+     * @param options - Wait options
+     * @returns The completed job
+     * @throws {Error} If the job doesn't complete within the timeout
+     */
+    waitForJob(jobId: string, options?: WaitForJobOptions): Promise<Job>;
+    /**
+     * Create a voice cloning job.
+     *
+     * @param options - Voice cloning options
+     * @returns The created job
+     */
+    cloneVoice(options: CloneVoiceOptions): Promise<Job>;
+    /**
+     * Create a voice synthesis (text-to-speech) job.
+     *
+     * @param options - Voice synthesis options
+     * @returns The created job
+     */
+    synthesizeVoice(options: SynthesizeVoiceOptions): Promise<Job>;
+    /**
+     * List all voices in the user's voice library.
+     *
+     * @returns List of voices
+     */
+    listVoices(): Promise<Voice[]>;
+    /**
+     * Get a voice by ID.
+     *
+     * @param voiceId - The voice ID
+     * @returns The voice
+     */
+    getVoice(voiceId: string): Promise<Voice>;
+    /**
+     * Create a new voice in the voice library.
+     *
+     * @param options - Create voice options
+     * @returns The created voice
+     */
+    createVoice(options: CreateVoiceOptions): Promise<Voice>;
+    /**
+     * Update a voice in the voice library.
+     *
+     * @param options - Update voice options
+     * @returns The updated voice
+     */
+    updateVoice(options: UpdateVoiceOptions): Promise<Voice>;
+    /**
+     * Delete a voice from the voice library.
+     *
+     * @param voiceId - The voice ID
+     * @returns True if successful
+     */
+    deleteVoice(voiceId: string): Promise<boolean>;
+    /**
+     * Generate a presigned URL for uploading voice audio.
+     *
+     * @param options - Upload URL options
+     * @returns Upload URL details
+     */
+    generateVoiceUploadUrl(options: GenerateVoiceUploadUrlOptions): Promise<UploadUrl>;
+    /**
+     * Get current billing period usage statistics.
+     *
+     * @returns Current usage including credits, plan limits, and subscription details
+     */
+    getUsage(): Promise<Usage>;
+    /**
+     * Get daily usage statistics for the past 30 days.
+     *
+     * @returns List of daily usage records grouped by task type
+     */
+    getUsageHistory(): Promise<DailyUsage[]>;
+    /**
+     * Get the currently authenticated user's profile.
+     *
+     * @returns User profile information
+     */
+    getMe(): Promise<User>;
+    /**
+     * Update the currently authenticated user's profile.
+     *
+     * @param options - Update user options
+     * @returns Updated user profile
+     */
+    updateMe(options: UpdateUserOptions): Promise<User>;
+    /**
+     * Get the current rate limit status for creating dubbing jobs.
+     *
+     * @returns Rate limit status including remaining count and limit
+     */
+    getRateLimit(): Promise<RateLimit>;
+}
+
+/**
+ * Exceptions for Subformer SDK
+ */
+/** Base error for Subformer SDK */
+declare class SubformerError extends Error {
+    readonly statusCode?: number;
+    readonly code?: string;
+    readonly data?: unknown;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        code?: string;
+        data?: unknown;
+    });
+}
+/** Raised when API authentication fails */
+declare class AuthenticationError extends SubformerError {
+    constructor(message?: string);
+}
+/** Raised when a resource is not found */
+declare class NotFoundError extends SubformerError {
+    constructor(message?: string);
+}
+/** Raised when rate limit is exceeded */
+declare class RateLimitError extends SubformerError {
+    constructor(message?: string);
+}
+/** Raised when request validation fails */
+declare class ValidationError extends SubformerError {
+    constructor(message: string, data?: unknown);
+}
+
+export { AuthenticationError, type CloneVoiceOptions, type CreateVoiceOptions, type DailyUsage, type DubOptions, type DubSource, type GenerateVoiceUploadUrlOptions, type Job, type JobMetadata, type JobProgress, type JobState, type JobType, type Language, type ListJobsOptions, NotFoundError, type PaginatedJobs, type PresetVoice, type RateLimit, RateLimitError, Subformer, SubformerError, type SubformerOptions, type SynthesizeVoiceOptions, type TargetVoice, type UpdateUserOptions, type UpdateVoiceOptions, type UploadUrl, type UploadedVoice, type Usage, type UsageData, type User, ValidationError, type Voice, type WaitForJobOptions };