@explorins/pers-sdk 2.2.0-alpha.3 → 2.3.2

package/dist/chunks/{pers-sdk-DEfiDbIs.cjs → pers-sdk-CVsokrmI.cjs}

@@ -7,8 +7,8 @@ var userStatus = require('../user-status.cjs');
 var tokenService = require('./token-service-CnnrCOsg.cjs');
 var businessMembershipService = require('./business-membership-service-Dkb780NX.cjs');
 var campaign = require('../campaign.cjs');
-var redemptionService = require('./redemption-service-KamEndzB.cjs');
-var transactionRequest_builder = require('./transaction-request.builder-D8pIzjYD.cjs');
+var redemptionService = require('./redemption-service-PnHyM2qu.cjs');
+var transactionRequest_builder = require('./transaction-request.builder-IU_rZIIM.cjs');
 var paymentService = require('./payment-service-Bkw7ZXev.cjs');
 var tenantManager = require('./tenant-manager-DR5eSEJw.cjs');
 var paginationUtils = require('./pagination-utils-B2jRHMSO.cjs');
@@ -1591,6 +1591,135 @@ const SDK_VERSION = "2.2.0-alpha.3";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
+/**
+ * Tracking Manager - Handles data source and platform tracking
+ *
+ * Manages attribution data for analytics across all user actions.
+ *
+ * @module @explorins/pers-sdk/core/tracking
+ */
+/**
+ * Manages data source and platform tracking state
+ */
+class TrackingManager {
+    constructor(options) {
+        this.configDataSource = options?.dataSource;
+        this.configPlatform = options?.platform;
+    }
+    /**
+     * Set data source tracking info (replaces existing)
+     *
+     * @example
+     * ```typescript
+     * tracking.setDataSource({
+     *   channel: 'mobile',
+     *   medium: 'push',
+     *   campaign: 'summer_2026',
+     * });
+     * ```
+     */
+    setDataSource(dataSource) {
+        this._dataSource = dataSource;
+    }
+    /**
+     * Update data source tracking info (merges with existing)
+     *
+     * @example
+     * ```typescript
+     * tracking.updateDataSource({
+     *   campaign: 'new_campaign',
+     * });
+     * ```
+     */
+    updateDataSource(dataSource) {
+        const existing = this._dataSource ?? this.configDataSource;
+        this._dataSource = { ...existing, ...dataSource };
+    }
+    /**
+     * Set platform info for analytics
+     *
+     * @example
+     * ```typescript
+     * tracking.setPlatform({
+     *   os: 'iOS',
+     *   osVersion: '17.4',
+     *   app: 'MyApp',
+     *   appVersion: '2.3.1',
+     *   deviceType: 'phone',
+     * });
+     * ```
+     */
+    setPlatform(platform) {
+        this._platform = platform;
+    }
+    /**
+     * Get current data source config
+     */
+    getDataSource() {
+        return this._dataSource ?? this.configDataSource;
+    }
+    /**
+     * Get current platform info
+     */
+    getPlatform() {
+        return this._platform ?? this.configPlatform;
+    }
+    /**
+     * Check if tracking is properly configured
+     *
+     * Returns warnings for missing recommended tracking data.
+     * Useful for development/debugging to ensure proper attribution.
+     */
+    validate() {
+        const warnings = [];
+        const dataSource = this.getDataSource();
+        const platform = this.getPlatform();
+        // Check channel for non-web contexts
+        if (!dataSource?.channel) {
+            warnings.push('No channel set. Native apps should set channel: "mobile"');
+        }
+        // Check platform info
+        if (!platform || Object.keys(platform).length === 0) {
+            warnings.push('No platform info set. Consider calling setPlatform() for better analytics');
+        }
+        return {
+            isValid: warnings.length === 0,
+            warnings,
+        };
+    }
+    /**
+     * Build HTTP headers for data source tracking
+     *
+     * @internal - Used by PersApiClient
+     */
+    buildHeaders() {
+        const headers = {};
+        const dataSource = this.getDataSource();
+        const platform = this.getPlatform();
+        if (dataSource) {
+            if (dataSource.channel) {
+                headers['x-source-channel'] = dataSource.channel;
+            }
+            if (dataSource.medium) {
+                headers['x-source-medium'] = dataSource.medium;
+            }
+            if (dataSource.campaign) {
+                headers['x-source-campaign'] = dataSource.campaign;
+            }
+            if (dataSource.source) {
+                headers['x-source'] = dataSource.source;
+            }
+            if (dataSource.referrer) {
+                headers['Referer'] = dataSource.referrer;
+            }
+        }
+        if (platform && Object.keys(platform).length > 0) {
+            headers['x-platform'] = JSON.stringify(platform);
+        }
+        return headers;
+    }
+}
+
 // packages/pers-sdk/src/core/pers-api-client.ts
 /**
  * PERS API Client - Platform-agnostic HTTP client with authentication
@@ -1639,6 +1768,11 @@ class PersApiClient {
         }
         this.authService = new AuthService(this.authApi, this.mergedConfig.authProvider);
         this.refreshManager = new TokenRefreshManager(this.authService, this.mergedConfig.authProvider);
+        // Initialize tracking manager
+        this.tracking = new TrackingManager({
+            dataSource: this.mergedConfig.dataSource,
+            platform: this.mergedConfig.platform,
+        });
         if (this.mergedConfig.authProvider) {
             this.initializationPromise = this.initialize();
         }
@@ -1923,24 +2057,8 @@ class PersApiClient {
         else if (this.mergedConfig.apiProjectKey) {
             headers['x-project-key'] = this.mergedConfig.apiProjectKey;
         }
-        // Add data source tracking headers
-        const dataSource = this.mergedConfig.dataSource;
-        if (dataSource) {
-            headers['x-source-channel'] = dataSource.channel;
-            if (dataSource.medium) {
-                headers['x-source-medium'] = dataSource.medium;
-            }
-            if (dataSource.campaign) {
-                headers['x-source-campaign'] = dataSource.campaign;
-            }
-            if (dataSource.source) {
-                headers['x-source'] = dataSource.source;
-            }
-            // Note: referrer is typically set by browser, but can be overridden
-            if (dataSource.referrer) {
-                headers['Referer'] = dataSource.referrer;
-            }
-        }
+        // Add tracking headers (data source + platform)
+        Object.assign(headers, this.tracking.buildHeaders());
         return headers;
     }
     // ==========================================
@@ -1964,6 +2082,33 @@ class PersApiClient {
     getOriginalConfig() {
         return this.config;
     }
+    // ==========================================
+    // DATA SOURCE TRACKING
+    // ==========================================
+    /** Set data source tracking info (replaces existing) */
+    setDataSource(dataSource) {
+        this.tracking.setDataSource(dataSource);
+    }
+    /** Update data source tracking info (merges with existing) */
+    updateDataSource(dataSource) {
+        this.tracking.updateDataSource(dataSource);
+    }
+    /** Set platform info for analytics */
+    setPlatform(platform) {
+        this.tracking.setPlatform(platform);
+    }
+    /** Get current data source config */
+    getDataSource() {
+        return this.tracking.getDataSource();
+    }
+    /** Get current platform info */
+    getPlatform() {
+        return this.tracking.getPlatform();
+    }
+    /** Validate tracking configuration (for debugging) */
+    validateTracking() {
+        return this.tracking.validate();
+    }
 }
 
 /**
@@ -3182,6 +3327,37 @@ class UserManager {
         });
         return result;
     }
+    /**
+     * Admin: Export users as CSV
+     *
+     * Generates a comprehensive CSV export of all tenant users for
+     * external analysis, reporting, or compliance purposes. This operation
+     * requires administrator privileges and creates a downloadable file.
+     *
+     * @param options - Optional date range filters
+     * @param options.dateFrom - Start date filter (ISO date string)
+     * @param options.dateTo - End date filter (ISO date string)
+     * @returns Promise resolving to CSV blob for download
+     * @throws {PersApiError} When not authenticated as administrator or export fails
+     *
+     * @example Export All Users
+     * ```typescript
+     * const csvBlob = await sdk.users.exportCSV();
+     * const downloadUrl = URL.createObjectURL(csvBlob);
+     * ```
+     *
+     * @example Export Users Within Date Range
+     * ```typescript
+     * const csvBlob = await sdk.users.exportCSV({
+     *   dateFrom: '2024-01-01',
+     *   dateTo: '2024-12-31'
+     * });
+     * ```
+     */
+    async exportCSV(options) {
+        const userApi = new user.UserApi(this.apiClient);
+        return userApi.exportCSV(options);
+    }
     /**
      * Get the user service for advanced operations
      *
@@ -4644,7 +4820,13 @@ class CampaignManager {
      * ```
      */
     async getCampaigns(options) {
-        return this.campaignService.getCampaigns(options);
+        // Convert Date objects to ISO strings for API compatibility
+        const normalizedOptions = options ? {
+            ...options,
+            startDate: options.startDate instanceof Date ? options.startDate.toISOString() : options.startDate,
+            endDate: options.endDate instanceof Date ? options.endDate.toISOString() : options.endDate,
+        } : undefined;
+        return this.campaignService.getCampaigns(normalizedOptions);
     }
     /**
      * Admin: Create new campaign
@@ -5293,6 +5475,60 @@ class CampaignManager {
     async removeTriggerSource(campaignId, triggerSourceId) {
         return this.campaignService.removeTriggerSourceFromCampaign(campaignId, triggerSourceId);
     }
+    /**
+     * Admin: Export campaigns as CSV
+     *
+     * Generates a comprehensive CSV export of all tenant campaigns for
+     * external analysis, reporting, or compliance purposes. This operation
+     * requires administrator privileges and creates a downloadable file.
+     *
+     * @param options - Optional date range filters
+     * @param options.dateFrom - Start date filter (ISO date string)
+     * @param options.dateTo - End date filter (ISO date string)
+     * @returns Promise resolving to CSV blob for download
+     * @throws {PersApiError} When not authenticated as administrator or export fails
+     *
+     * @example Export All Campaigns
+     * ```typescript
+     * const csvBlob = await sdk.campaigns.exportCSV();
+     * const downloadUrl = URL.createObjectURL(csvBlob);
+     * ```
+     *
+     * @example Export Campaigns Within Date Range
+     * ```typescript
+     * const csvBlob = await sdk.campaigns.exportCSV({
+     *   dateFrom: '2024-01-01',
+     *   dateTo: '2024-12-31'
+     * });
+     * ```
+     */
+    async exportCSV(options) {
+        const campaignApi = new campaign.CampaignApi(this.apiClient);
+        return campaignApi.exportCSV(options);
+    }
+    /**
+     * Admin: Export campaign claims as CSV
+     *
+     * Generates a comprehensive CSV export of all campaign claim records for
+     * external analysis, reporting, or compliance purposes. This operation
+     * requires administrator privileges and creates a downloadable file.
+     *
+     * @param options - Optional date range filters
+     * @param options.dateFrom - Start date filter (ISO date string)
+     * @param options.dateTo - End date filter (ISO date string)
+     * @returns Promise resolving to CSV blob for download
+     * @throws {PersApiError} When not authenticated as administrator or export fails
+     *
+     * @example Export All Claims
+     * ```typescript
+     * const csvBlob = await sdk.campaigns.exportClaimsCSV();
+     * const downloadUrl = URL.createObjectURL(csvBlob);
+     * ```
+     */
+    async exportClaimsCSV(options) {
+        const campaignApi = new campaign.CampaignApi(this.apiClient);
+        return campaignApi.exportClaimsCSV(options);
+    }
     /**
      * Get the full campaign service for advanced operations
      *
@@ -6099,6 +6335,60 @@ class RedemptionManager {
     async deleteRedemption(id) {
         return this.redemptionService.deleteRedemption(id);
     }
+    /**
+     * Admin: Export redemptions as CSV
+     *
+     * Generates a comprehensive CSV export of all tenant redemptions for
+     * external analysis, reporting, or compliance purposes. This operation
+     * requires administrator privileges and creates a downloadable file.
+     *
+     * @param options - Optional date range filters
+     * @param options.dateFrom - Start date filter (ISO date string)
+     * @param options.dateTo - End date filter (ISO date string)
+     * @returns Promise resolving to CSV blob for download
+     * @throws {PersApiError} When not authenticated as administrator or export fails
+     *
+     * @example Export All Redemptions
+     * ```typescript
+     * const csvBlob = await sdk.redemptions.exportCSV();
+     * const downloadUrl = URL.createObjectURL(csvBlob);
+     * ```
+     *
+     * @example Export Redemptions Within Date Range
+     * ```typescript
+     * const csvBlob = await sdk.redemptions.exportCSV({
+     *   dateFrom: '2024-01-01',
+     *   dateTo: '2024-12-31'
+     * });
+     * ```
+     */
+    async exportCSV(options) {
+        const redemptionApi = new redemptionService.RedemptionApi(this.apiClient);
+        return redemptionApi.exportCSV(options);
+    }
+    /**
+     * Admin: Export redemption redeems as CSV
+     *
+     * Generates a comprehensive CSV export of all redemption redeem records for
+     * external analysis, reporting, or compliance purposes. This operation
+     * requires administrator privileges and creates a downloadable file.
+     *
+     * @param options - Optional date range filters
+     * @param options.dateFrom - Start date filter (ISO date string)
+     * @param options.dateTo - End date filter (ISO date string)
+     * @returns Promise resolving to CSV blob for download
+     * @throws {PersApiError} When not authenticated as administrator or export fails
+     *
+     * @example Export All Redeems
+     * ```typescript
+     * const csvBlob = await sdk.redemptions.exportRedeemsCSV();
+     * const downloadUrl = URL.createObjectURL(csvBlob);
+     * ```
+     */
+    async exportRedeemsCSV(options) {
+        const redemptionApi = new redemptionService.RedemptionApi(this.apiClient);
+        return redemptionApi.exportRedeemsCSV(options);
+    }
     /**
      * Get the full redemption service for advanced operations
      *
@@ -6492,54 +6782,36 @@ class TransactionManager {
      * external analysis, reporting, or compliance purposes. This operation
      * requires administrator privileges and creates a downloadable file.
      *
+     * @param options - Optional date range filters
+     * @param options.dateFrom - Start date filter (ISO date string)
+     * @param options.dateTo - End date filter (ISO date string)
      * @returns Promise resolving to CSV blob for download
      * @throws {PersApiError} When not authenticated as administrator or export fails
      *
-     * @example
+     * @example Export All Transactions
      * ```typescript
-     * // Admin operation - export transaction data
-     * try {
-     *   const csvBlob = await sdk.transactions.exportTransactionsCSV();
-     *
-     *   // Create download link
-     *   const downloadUrl = URL.createObjectURL(csvBlob);
-     *   const link = document.createElement('a');
-     *   link.href = downloadUrl;
-     *   link.download = `transactions-${new Date().toISOString().split('T')[0]}.csv`;
-     *
-     *   // Trigger download
-     *   document.body.appendChild(link);
-     *   link.click();
-     *   document.body.removeChild(link);
-     *
-     *   // Clean up object URL
-     *   URL.revokeObjectURL(downloadUrl);
-     *
-     *   console.log('Transaction export downloaded successfully');
-     *
-     * } catch (error) {
-     *   console.log('Export failed:', error.message);
-     * }
+     * const csvBlob = await sdk.transactions.exportCSV();
+     * const downloadUrl = URL.createObjectURL(csvBlob);
      * ```
      *
-     * @example Server-side Export (Node.js)
+     * @example Export Transactions Within Date Range
      * ```typescript
-     * // Admin operation - server-side CSV export
-     * const csvBlob = await sdk.transactions.exportTransactionsCSV();
-     *
-     * // Convert blob to buffer for Node.js
-     * const buffer = Buffer.from(await csvBlob.arrayBuffer());
-     *
-     * // Save to file system
-     * const fs = require('fs');
-     * const filename = `transactions-export-${Date.now()}.csv`;
-     * fs.writeFileSync(filename, buffer);
-     *
-     * console.log(`Transaction data exported to ${filename}`);
+     * const csvBlob = await sdk.transactions.exportCSV({
+     *   dateFrom: '2024-01-01',
+     *   dateTo: '2024-12-31'
+     * });
      * ```
      */
-    async exportTransactionsCSV() {
-        return this.transactionService.exportTransactionsCSV();
+    async exportCSV(options) {
+        return this.transactionService.exportTransactionsCSV(options);
+    }
+    /**
+     * Admin: Export transactions as CSV
+     *
+     * @deprecated Use `exportCSV()` instead for consistent naming across all managers
+     */
+    async exportTransactionsCSV(options) {
+        return this.exportCSV(options);
     }
     /**
      * Prepare existing transaction for client-side signing
@@ -8745,10 +9017,10 @@ class WebhookApi {
             params.append('hookId', options.webhookId);
         if (options?.status)
             params.append('status', options.status);
-        if (options?.fromDate)
-            params.append('dateFrom', options.fromDate);
-        if (options?.toDate)
-            params.append('dateTo', options.toDate);
+        if (options?.dateFrom)
+            params.append('dateFrom', options.dateFrom);
+        if (options?.dateTo)
+            params.append('dateTo', options.dateTo);
         if (options?.page)
             params.append('page', String(options.page));
         if (options?.limit)
@@ -9237,7 +9509,7 @@ class WebhookManager {
      * // Get executions for specific webhook
      * const executions = await sdk.webhooks.getExecutions({
      *   webhookId: 'webhook-123',
-     *   fromDate: '2024-01-01'
+     *   dateFrom: '2024-01-01'
      * });
      * ```
      */
@@ -10620,6 +10892,28 @@ class BookingApi {
     async delete(id) {
         return this.apiClient.delete(`${this.basePath}/${id}`);
     }
+    // ==========================================
+    // CSV EXPORT
+    // ==========================================
+    /**
+     * ADMIN: Export bookings to CSV
+     *
+     * Returns a CSV file with booking data for the tenant.
+     * Supports date range filtering.
+     *
+     * @param options - Export options (dateFrom, dateTo in ISO format)
+     * @returns CSV blob
+     */
+    async exportCSV(options) {
+        const params = new URLSearchParams();
+        if (options?.dateFrom)
+            params.append('dateFrom', options.dateFrom);
+        if (options?.dateTo)
+            params.append('dateTo', options.dateTo);
+        const queryString = params.toString();
+        const url = `${this.basePath}/export/csv${queryString ? `?${queryString}` : ''}`;
+        return this.apiClient.get(url, 'blob');
+    }
 }
 
 /**
@@ -11072,6 +11366,28 @@ class PersSDK {
         this.setupWalletEventsAutoConnect();
         // Auto-restore session from stored tokens (if enabled, default: true)
         this.setupAutoRestoreSession();
+        // Dev-mode tracking validation (helps developers ensure proper attribution)
+        this.validateTrackingInDev();
+    }
+    /**
+     * Validate tracking configuration in development mode
+     * @internal
+     */
+    validateTrackingInDev() {
+        // Only run in development (check common env vars)
+        const isDev = (typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'development') ||
+            (typeof window !== 'undefined' && window.__DEV__);
+        if (!isDev)
+            return;
+        // Delay check to allow time for setDataSource/setPlatform calls
+        setTimeout(() => {
+            const result = this.apiClient.validateTracking();
+            if (!result.isValid) {
+                console.warn('[PERS SDK] Tracking configuration warnings:');
+                result.warnings.forEach(w => console.warn(`  ⚠️ ${w}`));
+                console.warn('[PERS SDK] Call sdk.setDataSource() and sdk.setPlatform() for better analytics.');
+            }
+        }, 2000);
     }
     /**
      * Setup automatic session restoration from stored tokens
@@ -11772,6 +12088,74 @@ class PersSDK {
         // Reset manager so it picks up new config
         this._walletEvents = undefined;
     }
+    // ==========================================
+    // DATA SOURCE TRACKING
+    // ==========================================
+    /**
+     * Set data source tracking for analytics attribution
+     *
+     * Use this to track where users and actions originate from.
+     * Web apps typically only need medium/campaign/source (channel is auto-detected).
+     * Native apps must set channel: 'mobile'.
+     *
+     * @param dataSource - Data source configuration
+     *
+     * @example Web app with UTM params
+     * ```typescript
+     * sdk.setDataSource({
+     *   medium: 'email',
+     *   campaign: 'summer_2026',
+     *   source: 'mailchimp',
+     * });
+     * ```
+     *
+     * @example Native app
+     * ```typescript
+     * sdk.setDataSource({
+     *   channel: 'mobile',
+     *   medium: 'push',
+     *   campaign: 'retention_30d',
+     * });
+     * ```
+     */
+    setDataSource(dataSource) {
+        this.apiClient.setDataSource(dataSource);
+    }
+    /**
+     * Update data source (merges with existing values)
+     *
+     * @param dataSource - Partial data source to merge
+     *
+     * @example Update campaign after deep link
+     * ```typescript
+     * sdk.updateDataSource({ campaign: 'new_campaign' });
+     * ```
+     */
+    updateDataSource(dataSource) {
+        this.apiClient.updateDataSource(dataSource);
+    }
+    /**
+     * Set platform info for device analytics
+     *
+     * Native apps should call this on initialization with device info.
+     * Web apps can optionally send browser/OS info.
+     *
+     * @param platform - Platform information
+     *
+     * @example Native app
+     * ```typescript
+     * sdk.setPlatform({
+     *   os: 'iOS',
+     *   osVersion: '17.4',
+     *   app: 'MyApp',
+     *   appVersion: '2.3.1',
+     *   deviceType: 'phone',
+     * });
+     * ```
+     */
+    setPlatform(platform) {
+        this.apiClient.setPlatform(platform);
+    }
     /**
      * Gets the API client for direct PERS API requests
      *
@@ -11858,6 +12242,7 @@ exports.SDK_USER_AGENT = SDK_USER_AGENT;
 exports.SDK_VERSION = SDK_VERSION;
 exports.StaticJwtAuthProvider = StaticJwtAuthProvider;
 exports.TokenManager = TokenManager;
+exports.TrackingManager = TrackingManager;
 exports.TransactionManager = TransactionManager;
 exports.TriggerSourceManager = TriggerSourceManager;
 exports.UserManager = UserManager;
@@ -11873,4 +12258,4 @@ exports.createPersEventsClient = createPersEventsClient;
 exports.createPersSDK = createPersSDK;
 exports.isFatalAuthErrorInMessage = isFatalAuthErrorInMessage;
 exports.mergeWithDefaults = mergeWithDefaults;
-//# sourceMappingURL=pers-sdk-DEfiDbIs.cjs.map
+//# sourceMappingURL=pers-sdk-CVsokrmI.cjs.map