@wowsql/sdk 3.4.0

package/dist/storage.js

@@ -0,0 +1,404 @@
+"use strict";
+/**
+ * WowSQL Storage SDK - S3 Storage management with automatic quota validation
+ *
+ * @version 2.1.0
+ * @license MIT
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WowSQLStorage = exports.StorageLimitExceededError = exports.StorageError = void 0;
+const axios_1 = __importDefault(require("axios"));
+const fs = __importStar(require("fs"));
+class StorageError extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = 'StorageError';
+    }
+}
+exports.StorageError = StorageError;
+class StorageLimitExceededError extends StorageError {
+    constructor(message, statusCode, response) {
+        super(message, statusCode, response);
+        this.name = 'StorageLimitExceededError';
+    }
+}
+exports.StorageLimitExceededError = StorageLimitExceededError;
+// ==================== Storage Client ====================
+/**
+ * WowSQL Storage Client - Manage S3 storage with automatic quota validation
+ *
+ * Features:
+ * - Automatic storage limit validation before upload
+ * - Real-time quota checking
+ * - File upload/download/delete operations
+ * - Presigned URL generation
+ * - Storage provisioning and management
+ *
+ * @example
+ * ```typescript
+ * const storage = new WowSQLStorage({
+ *   projectSlug: 'myproject',
+ *   apiKey: 'your_api_key'
+ * });
+ *
+ * // Check quota
+ * const quota = await storage.getQuota();
+ * console.log(`Available: ${quota.storage_available_gb.toFixed(2)} GB`);
+ *
+ * // Upload file (auto-validates limits)
+ * const fileBuffer = fs.readFileSync('document.pdf');
+ * const result = await storage.uploadFile(fileBuffer, 'document.pdf', {
+ *   folder: 'documents'
+ * });
+ *
+ * // List files
+ * const files = await storage.listFiles({ prefix: 'documents/' });
+ * ```
+ */
+class WowSQLStorage {
+    constructor(config) {
+        this.projectSlug = config.projectSlug;
+        this.autoCheckQuota = config.autoCheckQuota !== false;
+        const baseUrl = config.baseUrl || 'https://api.wowsql.com';
+        // Create axios instance
+        this.client = axios_1.default.create({
+            baseURL: baseUrl,
+            headers: {
+                'Authorization': `Bearer ${config.apiKey}`,
+            },
+            timeout: config.timeout || 60000, // 60s default for file uploads
+        });
+        // Add error interceptor
+        this.client.interceptors.response.use((response) => response, (error) => {
+            if (error.response) {
+                const errorData = error.response.data;
+                const errorMessage = errorData?.detail || errorData?.message || error.message;
+                // Check for storage limit exceeded
+                if (error.response.status === 413) {
+                    throw new StorageLimitExceededError(errorMessage, error.response.status, errorData);
+                }
+                throw new StorageError(errorMessage, error.response.status, errorData);
+            }
+            throw new StorageError(error.message);
+        });
+    }
+    /**
+     * Get storage quota and usage information
+     *
+     * @param forceRefresh - Force refresh quota from server (default: false)
+     * @returns Storage quota details
+     *
+     * @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}%`);
+     * ```
+     */
+    async getQuota(forceRefresh = false) {
+        if (this.quotaCache && !forceRefresh) {
+            return this.quotaCache;
+        }
+        const response = await this.client.get(`/api/v1/storage/s3/projects/${this.projectSlug}/quota`);
+        this.quotaCache = response.data;
+        return response.data;
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async checkUploadAllowed(fileSizeBytes) {
+        const quota = await this.getQuota(true);
+        const fileSizeGB = fileSizeBytes / (1024 ** 3);
+        if (fileSizeGB > quota.storage_available_gb) {
+            return {
+                allowed: false,
+                message: `Storage limit exceeded! File size: ${fileSizeGB.toFixed(4)} GB, ` +
+                    `Available: ${quota.storage_available_gb.toFixed(4)} GB. ` +
+                    `Upgrade your plan to get more storage.`
+            };
+        }
+        return {
+            allowed: true,
+            message: `Upload allowed. ${quota.storage_available_gb.toFixed(4)} GB available.`
+        };
+    }
+    /**
+     * 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
+     *
+     * @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' }
+     * );
+     * ```
+     */
+    async uploadFile(fileData, fileName, options) {
+        // Get file size
+        const fileSize = fileData instanceof Buffer ? fileData.length : fileData.size;
+        // Check quota if enabled
+        const shouldCheck = options?.checkQuota !== undefined ? options.checkQuota : this.autoCheckQuota;
+        if (shouldCheck) {
+            const check = await this.checkUploadAllowed(fileSize);
+            if (!check.allowed) {
+                throw new StorageLimitExceededError(check.message, 413);
+            }
+        }
+        // Prepare form data
+        const formData = new FormData();
+        const blob = fileData instanceof Buffer ? new Blob([fileData]) : fileData;
+        formData.append('file', blob, fileName);
+        // Build URL with query params
+        const params = new URLSearchParams();
+        if (options?.folder) {
+            params.append('folder', options.folder);
+        }
+        const url = `/api/v1/storage/s3/projects/${this.projectSlug}/upload${params.toString() ? '?' + params.toString() : ''}`;
+        // Upload
+        const response = await this.client.post(url, formData, {
+            headers: {
+                'Content-Type': 'multipart/form-data',
+            },
+        });
+        // Clear quota cache after upload
+        this.quotaCache = undefined;
+        return response.data;
+    }
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * const result = await storage.uploadFromPath(
+     *   'documents/report.pdf',
+     *   'report.pdf',
+     *   { folder: 'reports' }
+     * );
+     * ```
+     */
+    async uploadFromPath(filePath, fileName, options) {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        const fileBuffer = fs.readFileSync(filePath);
+        const name = fileName || filePath.split('/').pop() || 'file';
+        return this.uploadFile(fileBuffer, name, options);
+    }
+    /**
+     * List files in S3 bucket
+     *
+     * @param options - List options
+     * @returns Array of storage files
+     *
+     * @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`);
+     * }
+     * ```
+     */
+    async listFiles(options) {
+        const params = {};
+        if (options?.prefix)
+            params.prefix = options.prefix;
+        if (options?.maxKeys)
+            params.max_keys = options.maxKeys;
+        const response = await this.client.get(`/api/v1/storage/s3/projects/${this.projectSlug}/files`, { params });
+        return response.data.files || [];
+    }
+    /**
+     * Delete a file from S3 bucket
+     *
+     * @param fileKey - Path to file in bucket
+     * @returns Deletion result
+     *
+     * @example
+     * ```typescript
+     * const result = await storage.deleteFile('documents/old-file.pdf');
+     * console.log(result.message);
+     * ```
+     */
+    async deleteFile(fileKey) {
+        const response = await this.client.delete(`/api/v1/storage/s3/projects/${this.projectSlug}/files/${fileKey}`);
+        // Clear quota cache after delete
+        this.quotaCache = undefined;
+        return response.data;
+    }
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * const urlData = await storage.getFileUrl('photo.jpg', 7200);
+     * console.log(urlData.file_url); // Use this for downloads
+     * ```
+     */
+    async getFileUrl(fileKey, expiresIn = 3600) {
+        const response = await this.client.get(`/api/v1/storage/s3/projects/${this.projectSlug}/files/${fileKey}/url`, { params: { expires_in: expiresIn } });
+        return response.data;
+    }
+    /**
+     * Generate presigned URL for file operations
+     *
+     * @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
+     * });
+     * ```
+     */
+    async getPresignedUrl(fileKey, options) {
+        const response = await this.client.post(`/api/v1/storage/s3/projects/${this.projectSlug}/presigned-url`, {
+            file_key: fileKey,
+            expires_in: options?.expiresIn || 3600,
+            operation: options?.operation || 'get_object',
+        });
+        return response.data.url;
+    }
+    /**
+     * 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`);
+     * ```
+     */
+    async getStorageInfo() {
+        const response = await this.client.get(`/api/v1/storage/s3/projects/${this.projectSlug}/info`);
+        return response.data;
+    }
+    /**
+     * 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!
+     * ```
+     */
+    async provisionStorage(region = 'us-east-1') {
+        const response = await this.client.post(`/api/v1/storage/s3/projects/${this.projectSlug}/provision`, { region });
+        return response.data;
+    }
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    async getAvailableRegions() {
+        const response = await this.client.get('/api/v1/storage/s3/regions');
+        return response.data;
+    }
+}
+exports.WowSQLStorage = WowSQLStorage;
+exports.default = WowSQLStorage;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@wowsql/sdk",
+  "version": "3.4.0",
+  "description": "Official TypeScript/JavaScript SDK for WowSQL - MySQL Backend-as-a-Service with S3 Storage, type-safe queries and fluent API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build",
+    "publish:patch": "npm version patch && npm publish",
+    "publish:minor": "npm version minor && npm publish",
+    "publish:major": "npm version major && npm publish"
+  },
+  "keywords": [
+    "wowsql",
+    "mysql",
+    "database",
+    "backend-as-a-service",
+    "baas",
+    "api",
+    "rest",
+    "typescript",
+    "javascript",
+    "sdk",
+    "client",
+    "query-builder",
+    "orm",
+    "sql",
+    "aws-rds",
+    "cloud-database",
+    "s3",
+    "storage",
+    "file-upload",
+    "object-storage"
+  ],
+  "author": "WowSQL Team <support@wowsql.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wowsql/wowsql.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wowsql/wowsql/issues"
+  },
+  "homepage": "https://wowsql.com",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0"
+  }
+}