magically-sdk/MagicallyFiles.d.ts

Official SDK for Magically - Build mobile apps with AI

import { MagicallyAuth } from './MagicallyAuth';
import { SDKConfig, FileUploadOptions, FileListOptions, UploadedFile, FileListResponse } from './types';
export declare class MagicallyFiles {
    private config;
    private auth;
    private logger;
    private apiClient;
    constructor(config: SDKConfig, auth: MagicallyAuth);
    /**
     * Convert a URI (from camera, image picker, etc.) to a proper File object
     *
     * This is the CRITICAL step that LLMs often miss. All Expo camera/picker results
     * give you URIs, but the upload API needs proper File objects.
     *
     * Steps performed:
     * 1. Fetch the URI to get the actual binary data
     * 2. Convert response to blob
     * 3. Create proper File object with name and MIME type
     *
     * @param uri - URI from camera/picker (asset.uri or photo.uri)
     * @param fileName - Name for the file (include extension!)
     * @param mimeType - MIME type (e.g., 'image/jpeg', 'image/png')
     * @returns Proper File object ready for upload
     *
     * @example
     * // From camera
     * const photo = await cameraRef.current.takePictureAsync();
     * const file = await magically.files.convertUriToFile(
     *   photo.uri,
     *   'photo.jpg',
     *   'image/jpeg'
     * );
     *
     * @example
     * // From image picker
     * const result = await ImagePicker.launchImageLibraryAsync();
     * const asset = result.assets[0];
     * const file = await magically.files.convertUriToFile(
     *   asset.uri,
     *   asset.fileName || 'image.jpg',
     *   asset.mimeType || 'image/jpeg'
     * );
     */
    convertUriToFile(uri: string, fileName: string, mimeType?: string): Promise<File>;
    /**
     * Upload a file to Vercel Blob storage and save metadata to MongoDB
     * @param file - File object to upload (from file input or camera)
     * @param options - Upload options (tags, metadata)
     * @returns Uploaded file metadata
     */
    upload(file: File | Blob, options?: FileUploadOptions): Promise<UploadedFile>;
    /**
     * List uploaded files with filtering and pagination
     * @param options - List options (limit, skip, tags, mimeType)
     * @returns List of files with pagination info
     */
    list(options?: FileListOptions): Promise<FileListResponse>;
    /**
     * Delete a file from both Vercel Blob and MongoDB
     * @param fileId - MongoDB document ID of the file to delete
     * @returns Success confirmation
     */
    delete(fileId: string): Promise<{
        success: boolean;
        message: string;
    }>;
    /**
     * Upload multiple files in parallel
     * @param files - Array of files to upload
     * @param options - Upload options applied to all files
     * @returns Array of uploaded file metadata
     */
    uploadMultiple(files: (File | Blob)[], options?: FileUploadOptions): Promise<UploadedFile[]>;
    /**
     * Get files by tags
     * @param tags - Array of tags to filter by
     * @param options - Additional list options
     * @returns Files matching the tags
     */
    getByTags(tags: string[], options?: Omit<FileListOptions, 'tags'>): Promise<FileListResponse>;
    /**
     * Get files by MIME type
     * @param mimeType - MIME type to filter by (supports partial matching)
     * @param options - Additional list options
     * @returns Files matching the MIME type
     */
    getByMimeType(mimeType: string, options?: Omit<FileListOptions, 'mimeType'>): Promise<FileListResponse>;
    /**
     * Get image files only
     * @param options - List options
     * @returns Image files only
     */
    getImages(options?: Omit<FileListOptions, 'mimeType'>): Promise<FileListResponse>;
    /**
     * Get document files only (PDF, DOC, etc.)
     * @param options - List options
     * @returns Document files only
     */
    getDocuments(options?: Omit<FileListOptions, 'mimeType'>): Promise<FileListResponse>;
}