@wowsql/sdk 3.6.0 → 3.8.0

package/dist/storage.d.ts

@@ -1,395 +1,211 @@
 /**
- * WowSQL Storage SDK - S3 Storage management with automatic quota validation
+ * WowSQL Storage SDK - PostgreSQL-native file storage
  *
- * @version 2.1.0
+ * Files are stored as BYTEA inside each project's `storage` schema.
+ * No external S3 dependency — everything lives in PostgreSQL.
+ *
+ * @version 3.0.0
  * @license MIT
  */
+import { StorageError, StorageLimitExceededError } from './errors';
 export interface StorageConfig {
-    /** Project slug (e.g., 'myproject') */
-    projectSlug: string;
+    /** Project subdomain or full URL (e.g., 'myproject' or 'https://myproject.wowsql.com') */
+    projectUrl: string;
     /** API key for authentication */
     apiKey: string;
-    /** API base URL (default: https://api.wowsql.com) */
+    /** Project slug override (extracted from projectUrl if not provided) */
+    projectSlug?: string;
+    /** Full base URL override (e.g., 'https://custom.host/api/v1/storage') */
     baseUrl?: string;
+    /** Base domain (default: wowsql.com) */
+    baseDomain?: string;
+    /** Use HTTPS (default: true) */
+    secure?: boolean;
     /** Request timeout in milliseconds (default: 60000 for file uploads) */
     timeout?: number;
-    /** Automatically check quota before uploads (default: true) */
-    autoCheckQuota?: boolean;
+    /** Verify SSL certificates (default: true). Set to false for self-signed certs in dev. */
+    verifySsl?: boolean;
 }
-export interface StorageQuota {
-    /** Storage quota in GB based on plan */
-    storage_quota_gb: number;
-    /** Current storage used in GB */
-    storage_used_gb: number;
-    /** Additional storage expansion in GB */
-    storage_expansion_gb: number;
-    /** Available storage in GB */
-    storage_available_gb: number;
-    /** Usage percentage (0-100) */
-    usage_percentage: number;
-    /** Whether storage can be expanded (Enterprise only) */
-    can_expand_storage: boolean;
-    /** Whether user is on Enterprise plan */
-    is_enterprise: boolean;
-    /** Plan name (e.g., 'Free', 'Pro', 'Business', 'Enterprise') */
-    plan_name: string;
+export interface StorageBucket {
+    id: string;
+    name: string;
+    public: boolean;
+    file_size_limit: number | null;
+    allowed_mime_types: string[] | null;
+    created_at: string;
+    object_count: number;
+    total_size: number;
 }
 export interface StorageFile {
-    /** File key/path in bucket */
-    key: string;
-    /** File size in bytes */
+    id: string;
+    bucket_id: string;
+    name: string;
+    path: string;
+    mime_type: string | null;
     size: number;
-    /** Last modified timestamp */
-    last_modified: string;
-    /** ETag identifier */
-    etag: string;
-    /** Storage class (e.g., 'STANDARD') */
-    storage_class: string;
-    /** Presigned file URL (if requested) */
-    file_url?: string;
-    /** Public URL structure */
+    metadata: Record<string, any>;
+    created_at: string;
     public_url?: string;
+    /** Size in megabytes */
+    get sizeMb(): number;
+    /** Size in gigabytes */
+    get sizeGb(): number;
 }
-export interface FileUploadResult {
-    /** Upload success status */
-    success: boolean;
-    /** File key in bucket */
-    file_key: string;
-    /** File size in bytes */
-    file_size: number;
-    /** Bucket name */
-    bucket_name: string;
-    /** Optional presigned URL */
-    url?: string;
-    /** Success message */
-    message: string;
-}
-export interface FileUrlResult {
-    /** File key */
-    file_key: string;
-    /** Presigned download URL */
-    file_url: string;
-    /** Public URL structure */
-    public_url: string;
-    /** URL expiration timestamp */
-    expires_at: string;
-    /** Bucket name */
-    bucket_name: string;
-    /** AWS region */
-    region: string;
-    /** File size in bytes (if available) */
-    size?: number;
-}
-export interface StorageInfo {
-    /** Storage ID */
-    s3_storage_id: number;
-    /** S3 bucket name */
-    bucket_name: string;
-    /** AWS region */
-    region: string;
-    /** Storage status ('active', 'disabled', etc.) */
-    status: string;
-    /** Total number of objects */
-    total_objects: number;
-    /** Total size in bytes */
+export interface StorageQuota {
+    total_files: number;
     total_size_bytes: number;
-    /** Total size in GB */
     total_size_gb: number;
-    /** Provisioning timestamp */
-    provisioned_at?: string;
-    /** Creation timestamp */
-    created_at: string;
-}
-export interface ProvisionResult {
-    /** Success status */
-    success: boolean;
-    /** Storage ID */
-    s3_storage_id: number;
-    /** Bucket name */
-    bucket_name: string;
-    /** Bucket ARN */
-    bucket_arn: string;
-    /** AWS region */
-    region: string;
-    /** IAM user name */
-    iam_user_name: string;
-    /** Access credentials (SAVE THESE - shown only once!) */
-    credentials: {
-        access_key_id: string;
-        secret_access_key: string;
-    };
-    /** Provisioning timestamp */
-    provisioned_at: string;
-    /** Success message */
-    message: string;
-}
-export interface S3Region {
-    /** Region code (e.g., 'us-east-1') */
-    code: string;
-    /** Region name (e.g., 'US East N. Virginia') */
-    name: string;
-    /** Storage price per GB/month */
-    storage_price_gb: number;
-    /** Data transfer price per GB */
-    transfer_price_gb: number;
-    /** Latency tier */
-    latency_tier: string;
-    /** Recommended region flag */
-    recommended: boolean;
+    file_types: Record<string, number>;
 }
-export declare class StorageError extends Error {
-    statusCode?: number | undefined;
-    response?: any | undefined;
-    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
-}
-export declare class StorageLimitExceededError extends StorageError {
-    constructor(message: string, statusCode?: number, response?: any);
+export interface StorageStats {
+    total_files: number;
+    total_size_bytes: number;
+    total_size_gb: number;
+    bandwidth_used_bytes: number;
+    file_types: Record<string, number>;
 }
+export { StorageError, StorageLimitExceededError };
 /**
- * WowSQL Storage Client - Manage S3 storage with automatic quota validation
+ * WowSQL Storage Client — PostgreSQL-native file storage.
  *
- * Features:
- * - Automatic storage limit validation before upload
- * - Real-time quota checking
- * - File upload/download/delete operations
- * - Presigned URL generation
- * - Storage provisioning and management
+ * All files are stored directly in the project's PostgreSQL database
+ * inside the `storage` schema (buckets + objects as BYTEA).
  *
  * @example
  * ```typescript
  * const storage = new WowSQLStorage({
- *   projectSlug: 'myproject',
- *   apiKey: 'your_api_key'
+ *   projectUrl: 'myproject',
+ *   apiKey: 'wowsql_anon_...'
  * });
  *
- * // Check quota
- * const quota = await storage.getQuota();
- * console.log(`Available: ${quota.storage_available_gb.toFixed(2)} GB`);
+ * // Create a bucket
+ * const bucket = await storage.createBucket('avatars', { public: true });
  *
- * // Upload file (auto-validates limits)
- * const fileBuffer = fs.readFileSync('document.pdf');
- * const result = await storage.uploadFile(fileBuffer, 'document.pdf', {
- *   folder: 'documents'
- * });
+ * // Upload a file
+ * const file = document.querySelector('input[type="file"]').files[0];
+ * const result = await storage.upload('avatars', file, 'users/profile.jpg');
  *
  * // List files
- * const files = await storage.listFiles({ prefix: 'documents/' });
+ * const files = await storage.listFiles('avatars', { prefix: 'users/' });
+ *
+ * // Get public URL
+ * const url = storage.getPublicUrl('avatars', 'users/profile.jpg');
  * ```
  */
 export declare class WowSQLStorage {
     private client;
+    private baseUrl;
     private projectSlug;
-    private autoCheckQuota;
-    private quotaCache?;
     constructor(config: StorageConfig);
     /**
-     * Get storage quota and usage information
-     *
-     * @param forceRefresh - Force refresh quota from server (default: false)
-     * @returns Storage quota details
+     * Create a new storage bucket.
      *
-     * @example
-     * ```typescript
-     * const quota = await storage.getQuota();
-     * console.log(`Used: ${quota.storage_used_gb} GB`);
-     * console.log(`Available: ${quota.storage_available_gb} GB`);
-     * console.log(`Usage: ${quota.usage_percentage}%`);
-     * ```
+     * @param name - Bucket name (unique per project)
+     * @param options - Bucket configuration
      */
-    getQuota(forceRefresh?: boolean): Promise<StorageQuota>;
+    createBucket(name: string, options?: {
+        public?: boolean;
+        fileSizeLimit?: number;
+        allowedMimeTypes?: string[];
+    }): Promise<StorageBucket>;
     /**
-     * Check if file upload is allowed based on storage quota
-     *
-     * @param fileSizeBytes - Size of file to upload in bytes
-     * @returns Object with allowed status and message
-     *
-     * @example
-     * ```typescript
-     * const fileSize = 1024 * 1024 * 500; // 500 MB
-     * const check = await storage.checkUploadAllowed(fileSize);
-     * if (!check.allowed) {
-     *   console.error(check.message);
-     * }
-     * ```
+     * List all buckets in the project.
+     */
+    listBuckets(): Promise<StorageBucket[]>;
+    /**
+     * Get a specific bucket by name.
      */
-    checkUploadAllowed(fileSizeBytes: number): Promise<{
-        allowed: boolean;
+    getBucket(name: string): Promise<StorageBucket>;
+    /**
+     * Update bucket settings.
+     */
+    updateBucket(name: string, updates: {
+        name?: string;
+        public?: boolean;
+        fileSizeLimit?: number | null;
+        allowedMimeTypes?: string[] | null;
+    }): Promise<StorageBucket>;
+    /**
+     * Delete a bucket and all its files.
+     */
+    deleteBucket(name: string): Promise<{
+        success: boolean;
         message: string;
     }>;
     /**
-     * Upload a file to S3 storage with automatic quota validation
-     *
-     * @param fileData - File data as Buffer or Blob
-     * @param fileName - File name
-     * @param options - Upload options
-     * @returns Upload result
-     *
-     * @throws {StorageLimitExceededError} If storage quota would be exceeded
-     * @throws {StorageError} If upload fails
+     * Upload a file to a bucket.
      *
-     * @example
-     * ```typescript
-     * // Node.js - from file
-     * const fileBuffer = fs.readFileSync('photo.jpg');
-     * const result = await storage.uploadFile(fileBuffer, 'photo.jpg', {
-     *   folder: 'images',
-     *   contentType: 'image/jpeg'
-     * });
-     *
-     * // Browser - from File input
-     * const file = document.querySelector('input[type="file"]').files[0];
-     * const arrayBuffer = await file.arrayBuffer();
-     * const result = await storage.uploadFile(
-     *   Buffer.from(arrayBuffer),
-     *   file.name,
-     *   { folder: 'uploads' }
-     * );
-     * ```
+     * @param bucketName - Target bucket
+     * @param fileData - File data (File, Blob, or Buffer)
+     * @param path - Optional path within the bucket (e.g., 'users/avatar.png')
+     * @param fileName - Optional file name override
      */
-    uploadFile(fileData: Buffer | Blob, fileName: string, options?: {
-        folder?: string;
-        contentType?: string;
-        checkQuota?: boolean;
-    }): Promise<FileUploadResult>;
+    upload(bucketName: string, fileData: File | Blob | Buffer, path?: string, fileName?: string): Promise<StorageFile>;
     /**
-     * Upload a file from filesystem path (Node.js only)
-     *
-     * @param filePath - Path to local file
-     * @param fileName - Optional file name in bucket (defaults to filename)
-     * @param options - Upload options
-     * @returns Upload result
+     * Upload a file (compatibility alias for upload).
      *
-     * @example
-     * ```typescript
-     * const result = await storage.uploadFromPath(
-     *   'documents/report.pdf',
-     *   'report.pdf',
-     *   { folder: 'reports' }
-     * );
-     * ```
+     * @param bucketName - Target bucket
+     * @param fileData - File data (File, Blob, or Buffer)
+     * @param path - Optional path within the bucket
+     * @param fileName - Optional file name override
      */
-    uploadFromPath(filePath: string, fileName?: string, options?: {
-        folder?: string;
-        contentType?: string;
-        checkQuota?: boolean;
-    }): Promise<FileUploadResult>;
+    uploadFile(bucketName: string, fileData: File | Blob | Buffer, path?: string, fileName?: string): Promise<StorageFile>;
     /**
-     * List files in S3 bucket
+     * Upload a file from a local file path (Node.js only).
      *
-     * @param options - List options
-     * @returns Array of storage files
+     * @param filePath - Local file path to upload
+     * @param bucketName - Target bucket (defaults to 'default')
+     * @param path - Optional path within the bucket
+     */
+    uploadFromPath(filePath: string, bucketName?: string, path?: string): Promise<StorageFile>;
+    /**
+     * List files in a bucket.
      *
-     * @example
-     * ```typescript
-     * const files = await storage.listFiles({ prefix: 'documents/' });
-     * for (const file of files) {
-     *   console.log(`${file.key}: ${(file.size / 1024 / 1024).toFixed(2)} MB`);
-     * }
-     * ```
+     * @param bucketName - Bucket to list
+     * @param options - Filter and pagination options
      */
-    listFiles(options?: {
+    listFiles(bucketName: string, options?: {
         prefix?: string;
-        maxKeys?: number;
+        limit?: number;
+        offset?: number;
     }): Promise<StorageFile[]>;
     /**
-     * Delete a file from S3 bucket
-     *
-     * @param fileKey - Path to file in bucket
-     * @returns Deletion result
+     * Download a file. Returns binary data as ArrayBuffer.
      *
-     * @example
-     * ```typescript
-     * const result = await storage.deleteFile('documents/old-file.pdf');
-     * console.log(result.message);
-     * ```
+     * @param bucketName - Bucket name
+     * @param filePath - Path to file within the bucket
      */
-    deleteFile(fileKey: string): Promise<{
-        success: boolean;
-        message: string;
-        file_key: string;
-    }>;
+    download(bucketName: string, filePath: string): Promise<ArrayBuffer>;
     /**
-     * Get presigned URL for file access
-     *
-     * @param fileKey - Path to file in bucket
-     * @param expiresIn - URL validity in seconds (default: 3600 = 1 hour)
-     * @returns File URL and metadata
+     * Download a file and save to a local path (Node.js only).
      *
-     * @example
-     * ```typescript
-     * const urlData = await storage.getFileUrl('photo.jpg', 7200);
-     * console.log(urlData.file_url); // Use this for downloads
-     * ```
+     * @param bucketName - Bucket name
+     * @param filePath - Path to file within the bucket
+     * @param localPath - Local file path to save to
      */
-    getFileUrl(fileKey: string, expiresIn?: number): Promise<FileUrlResult>;
+    downloadToFile(bucketName: string, filePath: string, localPath: string): Promise<void>;
     /**
-     * Generate presigned URL for file operations
+     * Delete a file from a bucket.
      *
-     * @param fileKey - Path to file in bucket
-     * @param options - Presigned URL options
-     * @returns Presigned URL string
-     *
-     * @example
-     * ```typescript
-     * // Download URL
-     * const downloadUrl = await storage.getPresignedUrl('file.pdf');
-     *
-     * // Upload URL
-     * const uploadUrl = await storage.getPresignedUrl('new-file.pdf', {
-     *   operation: 'put_object',
-     *   expiresIn: 1800
-     * });
-     * ```
+     * @param bucketName - Bucket name
+     * @param filePath - Path to file within the bucket
      */
-    getPresignedUrl(fileKey: string, options?: {
-        expiresIn?: number;
-        operation?: 'get_object' | 'put_object';
-    }): Promise<string>;
+    deleteFile(bucketName: string, filePath: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
     /**
-     * Get S3 storage information for the project
-     *
-     * @returns Storage information
-     *
-     * @example
-     * ```typescript
-     * const info = await storage.getStorageInfo();
-     * console.log(`Bucket: ${info.bucket_name}`);
-     * console.log(`Region: ${info.region}`);
-     * console.log(`Objects: ${info.total_objects}`);
-     * console.log(`Size: ${info.total_size_gb.toFixed(2)} GB`);
-     * ```
+     * Get the public URL for a file in a public bucket.
+     * This URL works without authentication.
      */
-    getStorageInfo(): Promise<StorageInfo>;
+    getPublicUrl(bucketName: string, filePath: string): string;
     /**
-     * Provision S3 storage for the project
-     *
-     * **IMPORTANT**: Save the credentials returned! They're only shown once.
-     *
-     * @param region - AWS region (default: 'us-east-1')
-     * @returns Provisioning result with credentials
-     *
-     * @example
-     * ```typescript
-     * const result = await storage.provisionStorage('us-west-2');
-     * console.log(`Bucket: ${result.bucket_name}`);
-     * console.log(`Access Key: ${result.credentials.access_key_id}`);
-     * // SAVE THESE CREDENTIALS SECURELY!
-     * ```
+     * Get storage statistics for the project.
      */
-    provisionStorage(region?: string): Promise<ProvisionResult>;
+    getStats(): Promise<StorageStats>;
     /**
-     * Get list of available S3 regions with pricing
-     *
-     * @returns Array of available regions
-     *
-     * @example
-     * ```typescript
-     * const regions = await storage.getAvailableRegions();
-     * for (const region of regions) {
-     *   console.log(`${region.name}: $${region.storage_price_gb}/GB/month`);
-     * }
-     * ```
+     * Get storage quota for the project.
      */
-    getAvailableRegions(): Promise<S3Region[]>;
+    getQuota(): Promise<StorageQuota>;
 }
 export default WowSQLStorage;