@renderingvideo/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,559 @@
+/**
+ * RenderingVideo Node.js SDK - Type Definitions
+ */
+interface VideoMeta {
+    version: string;
+    width: number;
+    height: number;
+    fps?: number;
+    background?: string;
+}
+interface VideoConfig {
+    meta: VideoMeta;
+    tracks: Track[];
+    assets?: Record<string, Asset>;
+}
+interface Track {
+    clips: Clip[];
+}
+interface Clip {
+    type: string;
+    start: number;
+    duration: number;
+    [key: string]: unknown;
+}
+interface Asset {
+    type: 'image' | 'video' | 'audio' | 'font';
+    src: string;
+    [key: string]: unknown;
+}
+type TaskStatus = 'created' | 'rendering' | 'completed' | 'failed';
+interface Task {
+    success: boolean;
+    taskId: string;
+    videoTaskId?: string;
+    renderTaskId?: string;
+    previewUrl?: string;
+    viewerUrl?: string;
+    configUrl?: string;
+    videoUrl?: string;
+    status: TaskStatus;
+    quality?: string;
+    costCredits?: number;
+    cost?: number;
+    remainingCredits?: number;
+    width?: number;
+    height?: number;
+    duration?: number;
+    createdAt?: string;
+    completedAt?: string;
+    metadata?: Record<string, unknown>;
+    message?: string;
+    alreadyRendered?: boolean;
+}
+interface TaskList {
+    success: boolean;
+    tasks: Task[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+    };
+}
+type FileType = 'image' | 'video' | 'audio';
+interface UploadedFile {
+    id: string;
+    name: string;
+    url: string;
+    type: FileType;
+    mimeType: string;
+    size: number;
+    createdAt: string;
+}
+interface UploadResult {
+    success: boolean;
+    message: string;
+    count: number;
+    assets: UploadedFile[];
+}
+interface FileList {
+    success: boolean;
+    files: UploadedFile[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+    };
+}
+interface DeleteFileResult {
+    success: boolean;
+    fileId: string;
+    deleted: boolean;
+    message: string;
+}
+interface Credits {
+    success: boolean;
+    credits: number;
+    currency: string;
+}
+interface PreviewResult {
+    success: boolean;
+    tempId: string;
+    previewUrl: string;
+    viewerUrl?: string;
+    expiresIn: string;
+    note?: string;
+}
+interface PreviewConfig {
+    success: boolean;
+    tempId: string;
+    config: VideoConfig;
+}
+interface DeletePreviewResult {
+    success: boolean;
+    tempId: string;
+    deleted: boolean;
+    message: string;
+}
+interface ConvertPreviewResult {
+    success: boolean;
+    tempId: string;
+    converted: boolean;
+    taskId: string;
+    videoTaskId?: string;
+    previewUrl?: string;
+    viewerUrl?: string;
+    configUrl?: string;
+    message: string;
+}
+interface RenderPreviewResult {
+    success: boolean;
+    tempId: string;
+    converted: boolean;
+    convertMessage?: string;
+    configUrl?: string;
+    taskId: string;
+    renderTaskId?: string;
+    status: TaskStatus;
+    quality?: string;
+    width?: number;
+    height?: number;
+    cost?: number;
+    remainingCredits?: number;
+    message?: string;
+    previewUrl?: string;
+    viewerUrl?: string;
+}
+interface DeleteTaskResult {
+    success: boolean;
+    taskId: string;
+    videoTaskId?: string;
+    deleted: boolean;
+    remoteDeleted: boolean;
+    message: string;
+}
+interface ClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface CreateVideoOptions {
+    config: VideoConfig;
+    metadata?: Record<string, unknown>;
+}
+interface ListTasksOptions {
+    page?: number;
+    limit?: number;
+    status?: TaskStatus;
+}
+interface RenderOptions {
+    webhookUrl?: string;
+    numWorkers?: number;
+}
+interface ListFilesOptions {
+    page?: number;
+    limit?: number;
+    type?: FileType;
+}
+interface UploadOptions {
+    file?: Blob | File;
+    files?: (Blob | File)[];
+}
+interface ConvertPreviewOptions {
+    category?: string;
+}
+interface RenderPreviewOptions {
+    category?: string;
+    webhookUrl?: string;
+    numWorkers?: number;
+}
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+interface WebhookPayload {
+    taskId: string;
+    renderTaskId: string;
+    status: 'completed' | 'failed';
+    videoUrl?: string;
+    error?: string | null;
+    timestamp: string;
+}
+
+/**
+ * RenderingVideo Node.js SDK - Main Client
+ */
+
+/**
+ * Video API Client
+ */
+declare class VideoClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    private request;
+    /**
+     * Create a new video task (does not start rendering)
+     * @example
+     * ```typescript
+     * const task = await client.video.create({
+     *   config: {
+     *     meta: { version: '2.0.0', width: 1920, height: 1080, fps: 30 },
+     *     tracks: [{ clips: [{ type: 'text', text: 'Hello World', start: 0, duration: 5 }] }]
+     *   },
+     *   metadata: { projectId: 'proj_123' }
+     * });
+     * ```
+     */
+    create(options: CreateVideoOptions): Promise<Task>;
+    /**
+     * List video tasks
+     * @example
+     * ```typescript
+     * const { tasks, pagination } = await client.video.list({ page: 1, limit: 20, status: 'completed' });
+     * ```
+     */
+    list(options?: ListTasksOptions): Promise<TaskList>;
+    /**
+     * Get task details by ID
+     * @example
+     * ```typescript
+     * const task = await client.video.get('abc123def456');
+     * console.log(task.status, task.videoUrl);
+     * ```
+     */
+    get(taskId: string): Promise<Task>;
+    /**
+     * Delete a video task permanently
+     * @example
+     * ```typescript
+     * const result = await client.video.delete('abc123def456');
+     * console.log(result.deleted, result.remoteDeleted);
+     * ```
+     */
+    delete(taskId: string): Promise<DeleteTaskResult>;
+    /**
+     * Trigger rendering for a task
+     * @example
+     * ```typescript
+     * const result = await client.video.render('abc123def456', {
+     *   webhookUrl: 'https://example.com/webhook',
+     *   numWorkers: 5
+     * });
+     * ```
+     */
+    render(taskId: string, options?: RenderOptions): Promise<Task>;
+    /**
+     * Create task and immediately start rendering (convenience method)
+     * @example
+     * ```typescript
+     * const task = await client.video.createAndRender({
+     *   config: { ... },
+     *   webhookUrl: 'https://example.com/webhook'
+     * });
+     * ```
+     */
+    createAndRender(options: CreateVideoOptions & RenderOptions): Promise<Task>;
+}
+/**
+ * File API Client
+ */
+declare class FileClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    private request;
+    /**
+     * Upload files (images, videos, audio)
+     * @example
+     * ```typescript
+     * // In Node.js with FormData
+     * const formData = new FormData();
+     * formData.append('file', fileBlob, 'image.png');
+     * const result = await client.files.upload(formData);
+     *
+     * // Multiple files
+     * formData.append('files', file1Blob, 'video.mp4');
+     * formData.append('files', file2Blob, 'audio.mp3');
+     * const result = await client.files.upload(formData);
+     * ```
+     */
+    upload(formData: FormData): Promise<UploadResult>;
+    /**
+     * Upload a single file from buffer (Node.js)
+     * @example
+     * ```typescript
+     * const buffer = fs.readFileSync('./image.png');
+     * const result = await client.files.uploadBuffer(buffer, 'image.png', 'image/png');
+     * ```
+     */
+    uploadBuffer(buffer: Buffer, filename: string, mimeType: string): Promise<UploadResult>;
+    /**
+     * Upload a single file from Blob/File
+     * @example
+     * ```typescript
+     * const blob = new Blob([data], { type: 'image/png' });
+     * const result = await client.files.uploadFile(blob, 'image.png');
+     * ```
+     */
+    uploadFile(file: Blob | File, filename?: string): Promise<UploadResult>;
+    /**
+     * List uploaded files
+     * @example
+     * ```typescript
+     * const { files, pagination } = await client.files.list({ type: 'image', limit: 50 });
+     * ```
+     */
+    list(options?: ListFilesOptions): Promise<FileList>;
+    /**
+     * Delete a file
+     * @example
+     * ```typescript
+     * const result = await client.files.delete('asset_001');
+     * ```
+     */
+    delete(fileId: string): Promise<DeleteFileResult>;
+    /**
+     * Get file by ID (convenience method - searches through list)
+     * @example
+     * ```typescript
+     * const file = await client.files.get('asset_001');
+     * ```
+     */
+    get(fileId: string): Promise<UploadedFile | null>;
+}
+/**
+ * Preview API Client
+ */
+declare class PreviewClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    private request;
+    /**
+     * Create a temporary preview link (7 days validity, no credits consumed)
+     * @example
+     * ```typescript
+     * const preview = await client.preview.create({
+     *   meta: { version: '2.0.0', width: 1920, height: 1080 },
+     *   tracks: [{ clips: [{ type: 'text', text: 'Preview', start: 0, duration: 5 }] }]
+     * });
+     * console.log(preview.previewUrl, preview.tempId);
+     * ```
+     */
+    create(config: VideoConfig): Promise<PreviewResult>;
+    /**
+     * Get preview configuration
+     * @example
+     * ```typescript
+     * const { config } = await client.preview.get('temp_abc123');
+     * ```
+     */
+    get(tempId: string): Promise<PreviewConfig>;
+    /**
+     * Delete a preview link
+     * @example
+     * ```typescript
+     * const result = await client.preview.delete('temp_abc123');
+     * ```
+     */
+    delete(tempId: string): Promise<DeletePreviewResult>;
+    /**
+     * Convert preview to permanent task (does not start rendering)
+     * @example
+     * ```typescript
+     * const result = await client.preview.convert('temp_abc123', { category: 'marketing' });
+     * console.log(result.taskId);
+     * ```
+     */
+    convert(tempId: string, options?: ConvertPreviewOptions): Promise<ConvertPreviewResult>;
+    /**
+     * Convert preview to permanent task and immediately start rendering
+     * @example
+     * ```typescript
+     * const result = await client.preview.render('temp_abc123', {
+     *   webhookUrl: 'https://example.com/webhook'
+     * });
+     * console.log(result.taskId, result.status);
+     * ```
+     */
+    render(tempId: string, options?: RenderPreviewOptions): Promise<RenderPreviewResult>;
+}
+/**
+ * Main RenderingVideo SDK Client
+ *
+ * @example
+ * ```typescript
+ * import { RenderingVideo } from '@renderingvideo/sdk';
+ *
+ * const client = new RenderingVideo({ apiKey: 'sk-xxx' });
+ *
+ * // Create and render a video
+ * const task = await client.video.create({ config: { ... } });
+ * await client.video.render(task.taskId);
+ *
+ * // Check credits
+ * const { credits } = await client.credits.get();
+ *
+ * // Upload files
+ * const { assets } = await client.files.uploadFile(imageBlob);
+ * ```
+ */
+declare class RenderingVideo {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private _video;
+    private _files;
+    private _preview;
+    constructor(options: ClientOptions);
+    constructor(apiKey: string, options?: Partial<Omit<ClientOptions, 'apiKey'>>);
+    /**
+     * Video API operations
+     */
+    get video(): VideoClient;
+    /**
+     * File API operations (upload, list, delete)
+     */
+    get files(): FileClient;
+    /**
+     * Preview API operations
+     */
+    get preview(): PreviewClient;
+    /**
+     * Credits API operations
+     */
+    get credits(): CreditsClient;
+    /**
+     * Get masked API key for logging
+     */
+    get apiKeyPreview(): string;
+    /**
+     * Get the base URL being used
+     */
+    get baseURL(): string;
+}
+/**
+ * Credits API Client
+ */
+declare class CreditsClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(baseUrl: string, apiKey: string, timeout: number);
+    /**
+     * Get current credit balance
+     * @example
+     * ```typescript
+     * const { credits } = await client.credits.get();
+     * console.log(`You have ${credits} credits remaining`);
+     * ```
+     */
+    get(): Promise<Credits>;
+    /**
+     * Check if user has enough credits for a render
+     * @example
+     * ```typescript
+     * const hasCredits = await client.credits.hasEnough(100);
+     * ```
+     */
+    hasEnough(required: number): Promise<boolean>;
+}
+
+/**
+ * RenderingVideo Node.js SDK - Error Classes
+ */
+declare class RenderingVideoError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+}
+declare class AuthenticationError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class InvalidApiKeyError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class InsufficientCreditsError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class ValidationError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class NotFoundError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class RateLimitError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class AlreadyRenderingError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class UploadError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class StorageLimitError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class RemoteError extends RenderingVideoError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * RenderingVideo Node.js SDK
+ *
+ * Official Node.js SDK for the RenderingVideo API
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { RenderingVideo } from '@renderingvideo/sdk';
+ *
+ * const client = new RenderingVideo({ apiKey: 'sk-xxx' });
+ *
+ * // Create a video task
+ * const task = await client.video.create({
+ *   config: {
+ *     meta: { version: '2.0.0', width: 1920, height: 1080, fps: 30 },
+ *     tracks: [{ clips: [{ type: 'text', text: 'Hello World', start: 0, duration: 5 }] }]
+ *   }
+ * });
+ *
+ * // Start rendering
+ * await client.video.render(task.taskId, {
+ *   webhookUrl: 'https://example.com/webhook'
+ * });
+ *
+ * // Check credits
+ * const { credits } = await client.credits.get();
+ * ```
+ */
+
+export { AlreadyRenderingError, type ApiResponse, type Asset, AuthenticationError, type ClientOptions, type Clip, type ConvertPreviewOptions, type ConvertPreviewResult, type CreateVideoOptions, type Credits, CreditsClient, type DeleteFileResult, type DeletePreviewResult, type DeleteTaskResult, FileClient, type FileList, type FileType, InsufficientCreditsError, InvalidApiKeyError, type ListFilesOptions, type ListTasksOptions, NotFoundError, PreviewClient, type PreviewConfig, type PreviewResult, RateLimitError, RemoteError, type RenderOptions, type RenderPreviewOptions, type RenderPreviewResult, RenderingVideo, RenderingVideoError, StorageLimitError, type Task, type TaskList, type TaskStatus, type Track, UploadError, type UploadOptions, type UploadResult, type UploadedFile, ValidationError, VideoClient, type VideoConfig, type VideoMeta, type WebhookPayload, RenderingVideo as default };