@explorins/pers-sdk 1.6.4 → 1.6.9

package/dist/managers/campaign-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"campaign-manager.d.ts","sourceRoot":"","sources":["../../src/managers/campaign-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAqB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EACV,WAAW,EACX,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,yBAAyB,EACzB,0CAA0C,EAC1C,kBAAkB,EACnB,MAAM,iDAAiD,CAAC;AAEzD;;;;;GAKG;AACH,qBAAa,eAAe;IAGd,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,WAAW,CAAc;gBAEb,SAAS,EAAE,aAAa;IAI5C;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAIlD;;;;;OAKG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/D;;;;;OAKG;IACG,aAAa,CAAC,YAAY,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIrF;;;;OAIG;IACG,aAAa,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIlD;;;;;OAKG;IACG,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAI/D;;;;;OAKG;IACG,cAAc,CAAC,YAAY,EAAE,wBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC;IAIlF;;;;;;OAMG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,wBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC;IAItG;;;;;OAKG;IACG,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAIpE;;;;;OAKG;IACG,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAIrE;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAI1D;;;;;;OAMG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAIrF;;;;;;OAMG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,yBAAyB,GAAG,OAAO,CAAC,WAAW,CAAC;IAI7G;;;;;;OAMG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI5F;;;;;;OAMG;IACG,+BAA+B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,0CAA0C,GAAG,OAAO,CAAC,WAAW,CAAC;IAIvI;;;;;;;OAOG;IACG,gCAAgC,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,0CAA0C,GAAG,OAAO,CAAC,WAAW,CAAC;IAI9J;;;;;;OAMG;IACG,gCAAgC,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAItG;;;;OAIG;IACG,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAItD;;;;;OAKG;IACG,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAI5E;;;;;OAKG;IACG,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIpF;;;;OAIG;IACH,cAAc,IAAI,WAAW;CAG9B"}
+{"version":3,"file":"campaign-manager.d.ts","sourceRoot":"","sources":["../../src/managers/campaign-manager.ts"],"names":[],"mappings":"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"}

package/dist/managers/donation-manager.d.ts

@@ -1,5 +1,5 @@
 import { PersApiClient } from '../core/pers-api-client';
-import { DonationSDK } from '../donation';
+import { DonationService } from '../donation';
 import type { DonationTypeDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
 /**
  * Donation Manager - Clean, high-level interface for donation operations
@@ -9,7 +9,7 @@ import type { DonationTypeDTO } from '../shared/interfaces/pers-shared-lib.inter
  */
 export declare class DonationManager {
     private apiClient;
-    private donationSDK;
+    private donationService;
     constructor(apiClient: PersApiClient);
     /**
      * Get available donation types
@@ -18,10 +18,10 @@ export declare class DonationManager {
      */
     getDonationTypes(): Promise<DonationTypeDTO[]>;
     /**
-     * Get the full donation SDK for advanced operations
+     * Get the full donation service for advanced operations
      *
-     * @returns DonationSDK instance
+     * @returns DonationService instance
      */
-    getDonationSDK(): DonationSDK;
+    getDonationService(): DonationService;
 }
 //# sourceMappingURL=donation-manager.d.ts.map

package/dist/managers/donation-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"donation-manager.d.ts","sourceRoot":"","sources":["../../src/managers/donation-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAqB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAEvF;;;;;GAKG;AACH,qBAAa,eAAe;IAGd,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,WAAW,CAAc;gBAEb,SAAS,EAAE,aAAa;IAI5C;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAIpD;;;;OAIG;IACH,cAAc,IAAI,WAAW;CAG9B"}
+{"version":3,"file":"donation-manager.d.ts","sourceRoot":"","sources":["../../src/managers/donation-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAe,eAAe,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAEvF;;;;;GAKG;AACH,qBAAa,eAAe;IAGd,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,eAAe,CAAkB;gBAErB,SAAS,EAAE,aAAa;IAK5C;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAIpD;;;;OAIG;IACH,kBAAkB,IAAI,eAAe;CAGtC"}

package/dist/managers/file-manager.d.ts

@@ -4,8 +4,64 @@ import type { SignedUrlRequest, FileUploadEntityType } from '../file/models';
 /**
  * File Manager - Clean, high-level interface for file operations
  *
- * Provides a simplified API for common file management tasks while maintaining
- * access to the full file SDK for advanced use cases.
+ * Provides a comprehensive API for file management including secure file uploads,
+ * download URLs, media optimization, and cloud storage integration. Handles file
+ * operations for various entity types including tokens, campaigns, businesses,
+ * and user profiles with automatic security and optimization features.
+ *
+ * @group Managers
+ * @category File Management
+ *
+ * @example Basic File Upload
+ * ```typescript
+ * // Get signed URL for uploading a campaign image
+ * const uploadUrl = await sdk.files.getSignedPutUrl(
+ *   'campaign-123',
+ *   'campaign',
+ *   'jpg'
+ * );
+ *
+ * // Upload file using the signed URL
+ * const file = document.getElementById('fileInput').files[0];
+ * const response = await fetch(uploadUrl, {
+ *   method: 'PUT',
+ *   body: file,
+ *   headers: { 'Content-Type': file.type }
+ * });
+ *
+ * console.log('File uploaded successfully:', response.ok);
+ * ```
+ *
+ * @example File Access and Optimization
+ * ```typescript
+ * // Get secure download URL
+ * const downloadUrl = await sdk.files.getSignedGetUrl(
+ *   'token-456',
+ *   'token',
+ *   3600  // 1 hour expiry
+ * );
+ *
+ * // Get optimized thumbnail
+ * const thumbnail = await sdk.files.optimizeMedia(
+ *   downloadUrl,
+ *   300,  // width
+ *   300   // height
+ * );
+ *
+ * console.log('Thumbnail URL:', thumbnail);
+ * ```
+ *
+ * @example Advanced File Operations
+ * ```typescript
+ * // Use flexible signed URL API
+ * const customUrl = await sdk.files.getSignedUrl({
+ *   operation: 'GET',
+ *   entityId: 'business-789',
+ *   entityType: 'business',
+ *   expireSeconds: 7200,
+ *   contentType: 'image/png'
+ * });
+ * ```
  */
 export declare class FileManager {
     private apiClient;
@@ -14,41 +70,402 @@ export declare class FileManager {
     /**
      * Get signed URL for file upload
      *
-     * @param entityId - Entity ID to associate the file with
-     * @param entityType - Type of entity (token, campaign, etc.)
-     * @param fileExtension - File extension (e.g., 'jpg', 'png')
+     * Generates a secure, time-limited URL for uploading files to cloud storage.
+     * The URL provides direct upload access while maintaining security and
+     * associating files with specific entities in the loyalty system.
+     *
+     * @param entityId - Unique identifier of the entity to associate the file with
+     * @param entityType - Type of entity ('token', 'campaign', 'business', 'user', etc.)
+     * @param fileExtension - File extension without dot (e.g., 'jpg', 'png', 'pdf')
      * @returns Promise resolving to signed upload URL
+     * @throws {PersApiError} When entity not found or upload not authorized
+     *
+     * @example Campaign Image Upload
+     * ```typescript
+     * try {
+     *   // Get signed upload URL for campaign banner
+     *   const uploadUrl = await sdk.files.getSignedPutUrl(
+     *     'summer-campaign-2024',
+     *     'campaign',
+     *     'png'
+     *   );
+     *
+     *   console.log('Upload URL generated:', uploadUrl);
+     *
+     *   // Upload file from input element
+     *   const fileInput = document.getElementById('campaignBanner');
+     *   const file = fileInput.files[0];
+     *
+     *   if (file) {
+     *     const uploadResponse = await fetch(uploadUrl, {
+     *       method: 'PUT',
+     *       body: file,
+     *       headers: {
+     *         'Content-Type': file.type
+     *       }
+     *     });
+     *
+     *     if (uploadResponse.ok) {
+     *       console.log('✅ Campaign banner uploaded successfully');
+     *     } else {
+     *       console.log('❌ Upload failed:', uploadResponse.status);
+     *     }
+     *   }
+     *
+     * } catch (error) {
+     *   console.log('Upload URL generation failed:', error.message);
+     * }
+     * ```
+     *
+     * @example Token Logo Upload
+     * ```typescript
+     * // Upload logo for loyalty token
+     * const tokenLogoUrl = await sdk.files.getSignedPutUrl(
+     *   'loyalty-points-token',
+     *   'token',
+     *   'svg'
+     * );
+     *
+     * // Upload SVG file
+     * const svgFile = new File([svgContent], 'token-logo.svg', { type: 'image/svg+xml' });
+     * await fetch(tokenLogoUrl, {
+     *   method: 'PUT',
+     *   body: svgFile,
+     *   headers: { 'Content-Type': 'image/svg+xml' }
+     * });
+     *
+     * console.log('Token logo uploaded');
+     * ```
+     *
+     * @example Business Profile Image
+     * ```typescript
+     * // Upload business profile image
+     * const businessImageUrl = await sdk.files.getSignedPutUrl(
+     *   'partner-hotel-123',
+     *   'business',
+     *   'jpg'
+     * );
+     *
+     * // Handle file upload with progress tracking
+     * const file = selectedFile;
+     * const xhr = new XMLHttpRequest();
+     *
+     * xhr.upload.addEventListener('progress', (e) => {
+     *   if (e.lengthComputable) {
+     *     const percentComplete = (e.loaded / e.total) * 100;
+     *     console.log(`Upload progress: ${percentComplete}%`);
+     *   }
+     * });
+     *
+     * xhr.open('PUT', businessImageUrl);
+     * xhr.send(file);
+     * ```
      */
     getSignedPutUrl(entityId: string, entityType: FileUploadEntityType, fileExtension: string): Promise<string>;
     /**
      * Get signed URL for file access
      *
-     * @param entityId - Entity ID
-     * @param entityType - Type of entity
-     * @param expireSeconds - Optional expiration time in seconds
+     * Generates a secure, time-limited URL for accessing/downloading files from
+     * cloud storage. URLs automatically expire for security and can be used
+     * directly in image tags, download links, or API responses.
+     *
+     * @param entityId - Unique identifier of the entity the file is associated with
+     * @param entityType - Type of entity ('token', 'campaign', 'business', 'user', etc.)
+     * @param expireSeconds - Optional expiration time in seconds (default: 1 hour)
      * @returns Promise resolving to signed access URL
+     * @throws {PersApiError} When entity or file not found or access denied
+     *
+     * @example Image Display
+     * ```typescript
+     * try {
+     *   // Get URL for displaying token logo
+     *   const logoUrl = await sdk.files.getSignedGetUrl(
+     *     'vip-status-token',
+     *     'token',
+     *     3600  // 1 hour expiry
+     *   );
+     *
+     *   // Use in image element
+     *   const img = document.createElement('img');
+     *   img.src = logoUrl;
+     *   img.alt = 'VIP Status Token';
+     *   img.style.width = '64px';
+     *   img.style.height = '64px';
+     *
+     *   document.getElementById('tokenContainer').appendChild(img);
+     *
+     *   console.log('Token logo displayed');
+     *
+     * } catch (error) {
+     *   console.log('Failed to load token logo:', error.message);
+     *   // Show fallback image
+     *   img.src = '/images/default-token.png';
+     * }
+     * ```
+     *
+     * @example File Download
+     * ```typescript
+     * // Get download URL for campaign assets
+     * const downloadUrl = await sdk.files.getSignedGetUrl(
+     *   'holiday-campaign',
+     *   'campaign',
+     *   7200  // 2 hours for download
+     * );
+     *
+     * // Create download link
+     * const link = document.createElement('a');
+     * link.href = downloadUrl;
+     * link.download = 'holiday-campaign-assets.zip';
+     * link.textContent = 'Download Campaign Assets';
+     *
+     * document.body.appendChild(link);
+     *
+     * // Or trigger immediate download
+     * link.click();
+     * ```
+     *
+     * @example Gallery Display
+     * ```typescript
+     * // Display business gallery images
+     * const businessImages = ['image1', 'image2', 'image3'];
+     * const gallery = document.getElementById('businessGallery');
+     *
+     * for (const imageId of businessImages) {
+     *   try {
+     *     const imageUrl = await sdk.files.getSignedGetUrl(
+     *       `business-gallery-${imageId}`,
+     *       'business',
+     *       1800  // 30 minutes
+     *     );
+     *
+     *     const img = document.createElement('img');
+     *     img.src = imageUrl;
+     *     img.className = 'gallery-image';
+     *     img.loading = 'lazy';
+     *
+     *     gallery.appendChild(img);
+     *
+     *   } catch (error) {
+     *     console.log(`Failed to load image ${imageId}:`, error.message);
+     *   }
+     * }
+     * ```
      */
     getSignedGetUrl(entityId: string, entityType: FileUploadEntityType, expireSeconds?: number): Promise<string>;
     /**
      * Get signed URL for any file operation
      *
-     * @param request - Signed URL request
+     * Flexible method for generating signed URLs with custom parameters for
+     * various file operations including uploads, downloads, and deletions.
+     * Provides fine-grained control over URL generation and file access permissions.
+     *
+     * @param request - Signed URL request configuration
      * @returns Promise resolving to signed URL
+     * @throws {PersApiError} When request parameters are invalid or access denied
+     *
+     * @example Advanced Upload Configuration
+     * ```typescript
+     * // Create upload URL with specific content type and metadata
+     * const advancedUploadUrl = await sdk.files.getSignedUrl({
+     *   operation: 'PUT',
+     *   entityId: 'premium-nft-123',
+     *   entityType: 'token',
+     *   fileExtension: 'png',
+     *   contentType: 'image/png',
+     *   expireSeconds: 300,  // 5 minutes for security
+     *   metadata: {
+     *     creator: 'artist-456',
+     *     collection: 'premium-series',
+     *     rarity: 'legendary'
+     *   }
+     * });
+     *
+     * console.log('Advanced upload URL created:', advancedUploadUrl);
+     * ```
+     *
+     * @example Temporary Access URL
+     * ```typescript
+     * // Create very short-lived URL for sensitive document
+     * const secureUrl = await sdk.files.getSignedUrl({
+     *   operation: 'GET',
+     *   entityId: 'compliance-document-789',
+     *   entityType: 'business',
+     *   expireSeconds: 60,  // 1 minute only
+     *   accessLevel: 'admin-only'
+     * });
+     *
+     * // Use immediately
+     * window.open(secureUrl, '_blank');
+     * ```
+     *
+     * @example Batch Operations
+     * ```typescript
+     * // Generate multiple URLs for batch file operations
+     * const fileOperations = [
+     *   { operation: 'GET', entityId: 'doc1', entityType: 'campaign' },
+     *   { operation: 'GET', entityId: 'doc2', entityType: 'campaign' },
+     *   { operation: 'PUT', entityId: 'doc3', entityType: 'campaign', fileExtension: 'pdf' }
+     * ];
+     *
+     * const urls = await Promise.all(
+     *   fileOperations.map(op => sdk.files.getSignedUrl(op))
+     * );
+     *
+     * console.log('Generated batch URLs:', urls);
+     * ```
      */
     getSignedUrl(request: SignedUrlRequest): Promise<string>;
     /**
      * Optimize media file
      *
-     * @param url - Original file URL
-     * @param width - Optional target width
-     * @param height - Optional target height
+     * Creates optimized versions of media files with automatic resizing, format
+     * conversion, and compression. Perfect for generating thumbnails, responsive
+     * images, and bandwidth-optimized content while maintaining visual quality.
+     *
+     * @param url - Original file URL (can be signed or public URL)
+     * @param width - Optional target width in pixels
+     * @param height - Optional target height in pixels
      * @returns Promise resolving to optimized file URL
+     * @throws {PersApiError} When optimization fails or source file is invalid
+     *
+     * @example Responsive Image Sizes
+     * ```typescript
+     * // Get original campaign banner URL
+     * const originalUrl = await sdk.files.getSignedGetUrl('campaign-123', 'campaign');
+     *
+     * // Generate multiple optimized sizes
+     * const thumbnail = await sdk.files.optimizeMedia(originalUrl, 150, 150);
+     * const medium = await sdk.files.optimizeMedia(originalUrl, 400, 300);
+     * const large = await sdk.files.optimizeMedia(originalUrl, 800, 600);
+     *
+     * // Use in responsive image setup
+     * const img = document.createElement('img');
+     * img.src = medium;  // Default size
+     * img.srcset = `
+     *   ${thumbnail} 150w,
+     *   ${medium} 400w,
+     *   ${large} 800w
+     * `;
+     * img.sizes = '(max-width: 400px) 150px, (max-width: 800px) 400px, 800px';
+     *
+     * console.log('Responsive image configured');
+     * ```
+     *
+     * @example Avatar Generation
+     * ```typescript
+     * // Get user profile image and create avatars
+     * const profileUrl = await sdk.files.getSignedGetUrl('user-456', 'user');
+     *
+     * // Generate different avatar sizes
+     * const smallAvatar = await sdk.files.optimizeMedia(profileUrl, 32, 32);   // Nav bar
+     * const mediumAvatar = await sdk.files.optimizeMedia(profileUrl, 64, 64);  // Comments
+     * const largeAvatar = await sdk.files.optimizeMedia(profileUrl, 128, 128); // Profile page
+     *
+     * // Cache avatar URLs
+     * const avatars = {
+     *   small: smallAvatar,
+     *   medium: mediumAvatar,
+     *   large: largeAvatar
+     * };
+     *
+     * localStorage.setItem('userAvatars', JSON.stringify(avatars));
+     * console.log('User avatars generated and cached');
+     * ```
+     *
+     * @example Product Gallery Thumbnails
+     * ```typescript
+     * // Generate thumbnails for business product gallery
+     * const productImages = await getBusinessProductImages('business-789');
+     * const thumbnails = [];
+     *
+     * for (const productImage of productImages) {
+     *   try {
+     *     const originalUrl = await sdk.files.getSignedGetUrl(
+     *       productImage.id,
+     *       'business',
+     *       3600
+     *     );
+     *
+     *     const thumbnail = await sdk.files.optimizeMedia(originalUrl, 200, 200);
+     *
+     *     thumbnails.push({
+     *       id: productImage.id,
+     *       original: originalUrl,
+     *       thumbnail: thumbnail,
+     *       title: productImage.title
+     *     });
+     *
+     *   } catch (error) {
+     *     console.log(`Failed to optimize ${productImage.id}:`, error.message);
+     *   }
+     * }
+     *
+     * console.log(`Generated ${thumbnails.length} product thumbnails`);
+     *
+     * // Display thumbnail gallery
+     * thumbnails.forEach(item => {
+     *   const img = document.createElement('img');
+     *   img.src = item.thumbnail;
+     *   img.alt = item.title;
+     *   img.onclick = () => showLightbox(item.original);
+     *   gallery.appendChild(img);
+     * });
+     * ```
+     *
+     * @example Automatic Format Optimization
+     * ```typescript
+     * // Optimize with automatic format selection
+     * const tokenIcon = await sdk.files.getSignedGetUrl('token-123', 'token');
+     *
+     * // System automatically chooses best format (WebP, AVIF, etc.)
+     * const optimizedIcon = await sdk.files.optimizeMedia(tokenIcon, 48, 48);
+     *
+     * console.log('Optimized token icon (auto format):', optimizedIcon);
+     *
+     * // Use in token display
+     * document.querySelector('.token-icon').src = optimizedIcon;
+     * ```
      */
     optimizeMedia(url: string, width?: number, height?: number): Promise<string>;
     /**
      * Get the full file SDK for advanced operations
      *
-     * @returns FileService instance
+     * Provides access to the complete FileService instance for advanced file
+     * operations, batch processing, storage analytics, and operations not
+     * covered by the high-level manager methods.
+     *
+     * @returns FileService instance with full API access
+     *
+     * @example Advanced Operations
+     * ```typescript
+     * const fileSDK = sdk.files.getFileSDK();
+     *
+     * // Access storage analytics
+     * const storageStats = await fileSDK.getStorageAnalytics();
+     * console.log('Storage usage:', storageStats.totalSize);
+     *
+     * // Access batch file operations
+     * const batchResult = await fileSDK.batchDeleteFiles(['file1', 'file2', 'file3']);
+     *
+     * // Access file metadata management
+     * const metadata = await fileSDK.getFileMetadata('entity-123', 'campaign');
+     *
+     * // Access advanced optimization options
+     * const advancedOptimization = await fileSDK.optimizeMediaAdvanced(url, {
+     *   width: 400,
+     *   height: 300,
+     *   quality: 85,
+     *   format: 'webp',
+     *   progressive: true,
+     *   watermark: 'brand-logo'
+     * });
+     *
+     * // Access file upload monitoring
+     * const uploadProgress = fileSDK.monitorUploadProgress('upload-session-123');
+     * uploadProgress.on('progress', (percent) => {
+     *   console.log(`Upload: ${percent}%`);
+     * });
+     * ```
      */
     getFileSDK(): FileService;
 }

package/dist/managers/file-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-manager.d.ts","sourceRoot":"","sources":["../../src/managers/file-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAiB,WAAW,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,KAAK,EACV,gBAAgB,EAEhB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AAExB;;;;;GAKG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,OAAO,CAAc;gBAET,SAAS,EAAE,aAAa;IAI5C;;;;;;;OAOG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,oBAAoB,EAChC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;;;OAOG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,oBAAoB,EAChC,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D;;;;;;;OAOG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlF;;;;OAIG;IACH,UAAU,IAAI,WAAW;CAG1B"}
+{"version":3,"file":"file-manager.d.ts","sourceRoot":"","sources":["../../src/managers/file-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAiB,WAAW,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,KAAK,EACV,gBAAgB,EAEhB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,OAAO,CAAc;gBAET,SAAS,EAAE,aAAa;IAI5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6FG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,oBAAoB,EAChC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwFG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,oBAAoB,EAChC,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6DG;IACG,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8GG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,UAAU,IAAI,WAAW;CAG1B"}