@explorins/pers-sdk 1.6.4 → 1.6.9

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

@@ -1,158 +1,697 @@
 import { PersApiClient } from '../core/pers-api-client';
-import { CampaignSDK } from '../campaign';
+import { CampaignService } from '../campaign';
 import type { CampaignDTO, CampaignCreateRequestDTO, CampaignClaimRequestDTO, CampaignClaimDTO, TokenUnitCreateRequestDTO, CampaignBusinessEngagementCreateRequestDTO, CampaignTriggerDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
 /**
  * Campaign Manager - Clean, high-level interface for campaign operations
  *
- * Provides a simplified API for common campaign management tasks while maintaining
- * access to the full campaign SDK for advanced use cases.
+ * Provides a comprehensive API for loyalty campaign management including campaign
+ * discovery, reward claiming, business engagement tracking, and administrative
+ * campaign lifecycle operations. Campaigns are the core promotional mechanisms
+ * that drive user engagement and reward distribution in the loyalty ecosystem.
+ *
+ * @group Managers
+ * @category Campaign Management
+ *
+ * @example Basic Campaign Operations
+ * ```typescript
+ * // Get all available campaigns for users
+ * const campaigns = await sdk.campaigns.getActiveCampaigns();
+ * console.log(`${campaigns.length} active campaigns available`);
+ *
+ * // Get specific campaign details
+ * const campaign = await sdk.campaigns.getCampaignById('summer-promo-2024');
+ * console.log('Campaign:', campaign.title);
+ *
+ * // User claims campaign reward
+ * const claim = await sdk.campaigns.claimCampaign({
+ *   campaignId: 'summer-promo-2024',
+ *   businessId: 'partner-hotel-123'
+ * });
+ * ```
+ *
+ * @example User Campaign Management
+ * ```typescript
+ * // Get user's claimed campaigns
+ * const userClaims = await sdk.campaigns.getUserClaims();
+ *
+ * console.log('My Campaign Claims:');
+ * userClaims.forEach(claim => {
+ *   console.log(`- ${claim.campaign.title}`);
+ *   console.log(`  Rewards: ${claim.rewards?.length || 0} tokens`);
+ *   console.log(`  Date: ${claim.claimedAt}`);
+ * });
+ *
+ * // Check if user can claim specific campaign
+ * const eligibleCampaigns = campaigns.filter(c =>
+ *   !userClaims.some(claim => claim.campaignId === c.id)
+ * );
+ * ```
+ *
+ * @example Administrative Operations
+ * ```typescript
+ * // Admin: Create seasonal campaign
+ * const newCampaign = await sdk.campaigns.createCampaign({
+ *   title: 'Holiday Rewards',
+ *   description: 'Special holiday loyalty bonuses',
+ *   startDate: '2024-12-01',
+ *   endDate: '2024-12-31',
+ *   isActive: true
+ * });
+ *
+ * // Admin: Set up campaign rewards
+ * await sdk.campaigns.createCampaignTokenUnit(newCampaign.id, {
+ *   tokenId: 'loyalty-points',
+ *   amount: 500,
+ *   type: 'REWARD'
+ * });
+ * ```
  */
 export declare class CampaignManager {
     private apiClient;
-    private campaignSDK;
+    private campaignService;
     constructor(apiClient: PersApiClient);
     /**
      * Get all active campaigns
      *
-     * @returns Promise resolving to array of active campaigns
+     * Retrieves all currently active campaigns that users can discover and claim.
+     * Active campaigns are live promotional offers with valid date ranges and
+     * available rewards. Includes campaign details, eligibility requirements, and reward information.
+     *
+     * @returns Promise resolving to array of active campaign data
+     *
+     * @example
+     * ```typescript
+     * const activeCampaigns = await sdk.campaigns.getActiveCampaigns();
+     *
+     * console.log('Available Campaigns:');
+     * activeCampaigns.forEach(campaign => {
+     *   console.log(`\n📢 ${campaign.title}`);
+     *   console.log(`   ${campaign.description}`);
+     *   console.log(`   Valid: ${campaign.startDate} to ${campaign.endDate}`);
+     *   console.log(`   Rewards: ${campaign.tokenUnits?.length || 0} types`);
+     *
+     *   if (campaign.businessEngagements?.length) {
+     *     console.log(`   Partner businesses: ${campaign.businessEngagements.length}`);
+     *   }
+     * });
+     *
+     * // Filter campaigns by type or business
+     * const hotelCampaigns = activeCampaigns.filter(c =>
+     *   c.businessEngagements?.some(be =>
+     *     be.business?.businessType?.name?.includes('Hotel')
+     *   )
+     * );
+     * ```
      */
     getActiveCampaigns(): Promise<CampaignDTO[]>;
     /**
      * Get campaign by ID
      *
-     * @param campaignId - ID of the campaign
-     * @returns Promise resolving to campaign data
+     * Retrieves detailed information for a specific campaign including rewards,
+     * business partnerships, eligibility criteria, and claiming requirements.
+     *
+     * @param campaignId - Unique campaign identifier
+     * @returns Promise resolving to campaign data with complete details
+     * @throws {PersApiError} When campaign with specified ID is not found
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const campaign = await sdk.campaigns.getCampaignById('summer-promo-2024');
+     *
+     *   console.log('📢 Campaign Details:');
+     *   console.log('Title:', campaign.title);
+     *   console.log('Description:', campaign.description);
+     *   console.log('Active:', campaign.isActive);
+     *   console.log('Period:', `${campaign.startDate} to ${campaign.endDate}`);
+     *
+     *   console.log('\n💎 Rewards:');
+     *   campaign.tokenUnits?.forEach(unit => {
+     *     console.log(`- ${unit.amount} ${unit.token.symbol} (${unit.token.name})`);
+     *   });
+     *
+     *   console.log('\n🏢 Partner Businesses:');
+     *   campaign.businessEngagements?.forEach(engagement => {
+     *     console.log(`- ${engagement.business.displayName}`);
+     *   });
+     *
+     * } catch (error) {
+     *   console.log('Campaign not found:', error.message);
+     * }
+     * ```
      */
     getCampaignById(campaignId: string): Promise<CampaignDTO>;
     /**
      * Claim a campaign reward
      *
-     * @param claimRequest - Campaign claim data
-     * @returns Promise resolving to claim result
+     * Claims rewards from a campaign for the authenticated user. This action
+     * validates eligibility, processes reward distribution, and creates a permanent
+     * claim record. Users can typically claim each campaign only once.
+     *
+     * @param claimRequest - Campaign claim request with campaign and business context
+     * @returns Promise resolving to claim result with reward details
+     * @throws {PersApiError} When campaign is not claimable or user is not eligible
+     *
+     * @example Simple Campaign Claim
+     * ```typescript
+     * try {
+     *   const claim = await sdk.campaigns.claimCampaign({
+     *     campaignId: 'welcome-bonus',
+     *     businessId: 'partner-hotel-123'
+     *   });
+     *
+     *   console.log('✅ Campaign claimed successfully!');
+     *   console.log('Claim ID:', claim.id);
+     *   console.log('Claimed at:', claim.claimedAt);
+     *
+     *   if (claim.rewards?.length) {
+     *     console.log('\n💰 Rewards received:');
+     *     claim.rewards.forEach(reward => {
+     *       console.log(`- ${reward.amount} ${reward.token.symbol}`);
+     *     });
+     *   }
+     *
+     * } catch (error) {
+     *   console.log('Claim failed:', error.message);
+     * }
+     * ```
+     *
+     * @example Campaign Claim with Validation
+     * ```typescript
+     * // Check if campaign is still active
+     * const campaign = await sdk.campaigns.getCampaignById('limited-time-offer');
+     *
+     * if (campaign.isActive && new Date() <= new Date(campaign.endDate)) {
+     *   // Check if user already claimed
+     *   const userClaims = await sdk.campaigns.getUserClaims();
+     *   const alreadyClaimed = userClaims.some(c => c.campaignId === campaign.id);
+     *
+     *   if (!alreadyClaimed) {
+     *     const claim = await sdk.campaigns.claimCampaign({
+     *       campaignId: campaign.id,
+     *       businessId: 'partner-business-id'
+     *     });
+     *     console.log('Claim successful:', claim.id);
+     *   } else {
+     *     console.log('Campaign already claimed');
+     *   }
+     * }
+     * ```
      */
     claimCampaign(claimRequest: CampaignClaimRequestDTO): Promise<CampaignClaimDTO>;
     /**
      * Get user's campaign claims
      *
-     * @returns Promise resolving to array of user's claims
+     * Retrieves all campaigns that the authenticated user has successfully claimed.
+     * Includes claim timestamps, received rewards, and associated business context.
+     * Useful for user reward history and campaign participation tracking.
+     *
+     * @returns Promise resolving to array of user's campaign claims
+     *
+     * @example
+     * ```typescript
+     * const userClaims = await sdk.campaigns.getUserClaims();
+     *
+     * console.log(`📜 Campaign History (${userClaims.length} claims):`);
+     *
+     * userClaims.forEach((claim, index) => {
+     *   console.log(`\n${index + 1}. ${claim.campaign.title}`);
+     *   console.log(`   📅 Claimed: ${new Date(claim.claimedAt).toLocaleDateString()}`);
+     *   console.log(`   🏢 Business: ${claim.business?.displayName || 'N/A'}`);
+     *
+     *   if (claim.rewards?.length) {
+     *     console.log(`   💰 Rewards:`);
+     *     claim.rewards.forEach(reward => {
+     *       console.log(`      • ${reward.amount} ${reward.token.symbol}`);
+     *     });
+     *   }
+     * });
+     *
+     * // Calculate total rewards earned
+     * const totalRewards = userClaims.reduce((total, claim) => {
+     *   return total + (claim.rewards?.length || 0);
+     * }, 0);
+     *
+     * console.log(`\n🎁 Total reward items earned: ${totalRewards}`);
+     * ```
      */
     getUserClaims(): Promise<CampaignClaimDTO[]>;
     /**
      * Admin: Get all campaigns
      *
-     * @param active - Filter by active status
+     * Retrieves all campaigns in the system regardless of status. This operation
+     * requires administrator privileges and is used for comprehensive campaign
+     * management, reporting, and lifecycle operations.
+     *
+     * @param active - Optional filter to show only active or inactive campaigns
      * @returns Promise resolving to array of campaigns
+     * @throws {PersApiError} When not authenticated as administrator
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - get campaign overview
+     * const allCampaigns = await sdk.campaigns.getAllCampaigns();
+     * const activeCampaigns = await sdk.campaigns.getAllCampaigns(true);
+     * const inactiveCampaigns = await sdk.campaigns.getAllCampaigns(false);
+     *
+     * console.log('📊 Campaign Statistics:');
+     * console.log(`Total campaigns: ${allCampaigns.length}`);
+     * console.log(`Active campaigns: ${activeCampaigns.length}`);
+     * console.log(`Inactive campaigns: ${inactiveCampaigns.length}`);
+     *
+     * // Generate campaign performance report
+     * const campaignReport = allCampaigns.map(campaign => ({
+     *   title: campaign.title,
+     *   status: campaign.isActive ? 'Active' : 'Inactive',
+     *   period: `${campaign.startDate} to ${campaign.endDate}`,
+     *   businesses: campaign.businessEngagements?.length || 0,
+     *   rewardTypes: campaign.tokenUnits?.length || 0
+     * }));
+     * ```
      */
     getAllCampaigns(active?: boolean): Promise<CampaignDTO[]>;
     /**
      * Admin: Create new campaign
      *
-     * @param campaignData - Campaign data
-     * @returns Promise resolving to created campaign
+     * Creates a new loyalty campaign with specified configuration, rewards, and
+     * business partnerships. This operation requires administrator privileges
+     * and establishes a new promotional mechanism for user engagement.
+     *
+     * @param campaignData - Campaign configuration including title, dates, and settings
+     * @returns Promise resolving to created campaign data
+     * @throws {PersApiError} When not authenticated as admin or validation fails
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - create seasonal campaign
+     * const campaign = await sdk.campaigns.createCampaign({
+     *   title: 'Summer Travel Rewards',
+     *   description: 'Earn bonus points for summer bookings',
+     *   startDate: '2024-06-01T00:00:00Z',
+     *   endDate: '2024-08-31T23:59:59Z',
+     *   isActive: true,
+     *   isTestnet: false,
+     *   campaignType: 'SEASONAL'
+     * });
+     *
+     * console.log('✅ Campaign created:', campaign.title);
+     * console.log('Campaign ID:', campaign.id);
+     *
+     * // Set up campaign rewards
+     * await sdk.campaigns.createCampaignTokenUnit(campaign.id, {
+     *   tokenId: 'loyalty-points',
+     *   amount: 1000,
+     *   type: 'BONUS'
+     * });
+     * ```
      */
     createCampaign(campaignData: CampaignCreateRequestDTO): Promise<CampaignDTO>;
     /**
      * Admin: Update campaign
      *
-     * @param campaignId - ID of campaign to update
-     * @param campaignData - Updated campaign data
-     * @returns Promise resolving to updated campaign
+     * Updates an existing campaign's configuration, dates, or status. This operation
+     * requires administrator privileges and can modify most campaign properties
+     * while preserving existing claims and relationships.
+     *
+     * @param campaignId - ID of the campaign to update
+     * @param campaignData - Updated campaign configuration
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or campaign not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - extend campaign duration
+     * const updated = await sdk.campaigns.updateCampaign('summer-2024', {
+     *   title: 'Extended Summer Travel Rewards',
+     *   description: 'Earn bonus points for summer and early fall bookings',
+     *   endDate: '2024-09-30T23:59:59Z',  // Extended end date
+     *   isActive: true
+     * });
+     *
+     * console.log('Campaign updated:', updated.title);
+     * console.log('New end date:', updated.endDate);
+     * ```
      */
     updateCampaign(campaignId: string, campaignData: CampaignCreateRequestDTO): Promise<CampaignDTO>;
     /**
      * Admin: Toggle campaign active status
      *
-     * @param campaignId - ID of campaign to toggle
-     * @returns Promise resolving to updated campaign
+     * Toggles the active/inactive status of a campaign. Inactive campaigns are
+     * not available for new claims but existing claims remain valid. Requires
+     * administrator privileges.
+     *
+     * @param campaignId - ID of the campaign to toggle
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or campaign not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - temporarily disable campaign
+     * const updated = await sdk.campaigns.toggleCampaignStatus('problematic-campaign');
+     *
+     * console.log(`Campaign ${updated.isActive ? 'activated' : 'deactivated'}`);
+     * console.log('Status:', updated.isActive ? '✅ Active' : '❌ Inactive');
+     * ```
      */
     toggleCampaignStatus(campaignId: string): Promise<CampaignDTO>;
     /**
      * Admin: Toggle campaign testnet environment
      *
-     * @param campaignId - ID of campaign to toggle
-     * @returns Promise resolving to updated campaign
+     * Toggles the testnet/mainnet environment for a campaign. Testnet campaigns
+     * operate with test tokens and are used for validation before production deployment.
+     * Requires administrator privileges.
+     *
+     * @param campaignId - ID of the campaign to toggle
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or campaign not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - move campaign to production
+     * const updated = await sdk.campaigns.toggleCampaignTestnet('test-campaign');
+     *
+     * console.log(`Campaign moved to ${updated.isTestnet ? 'testnet' : 'mainnet'}`);
+     * ```
      */
     toggleCampaignTestnet(campaignId: string): Promise<CampaignDTO>;
     /**
      * Admin: Get campaign triggers
      *
-     * @returns Promise resolving to array of campaign triggers
+     * Retrieves all available campaign trigger mechanisms that can be used to
+     * automatically activate campaigns based on user actions or system events.
+     * Requires administrator privileges.
+     *
+     * @returns Promise resolving to array of campaign trigger definitions
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - view available triggers
+     * const triggers = await sdk.campaigns.getCampaignTriggers();
+     *
+     * console.log('Available Campaign Triggers:');
+     * triggers.forEach(trigger => {
+     *   console.log(`- ${trigger.name}: ${trigger.description}`);
+     *   console.log(`  Type: ${trigger.type}`);
+     *   console.log(`  Parameters: ${JSON.stringify(trigger.parameters)}`);
+     * });
+     * ```
      */
     getCampaignTriggers(): Promise<CampaignTriggerDTO[]>;
     /**
      * Admin: Set campaign trigger
      *
-     * @param campaignId - ID of campaign
-     * @param triggerId - ID of trigger to set
-     * @returns Promise resolving to updated campaign
+     * Associates a specific trigger mechanism with a campaign, enabling automatic
+     * campaign activation based on defined conditions. Requires administrator privileges.
+     *
+     * @param campaignId - ID of the campaign
+     * @param triggerId - ID of the trigger to associate
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or entities not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - set up automatic campaign trigger
+     * const updated = await sdk.campaigns.setCampaignTrigger(
+     *   'new-user-welcome',
+     *   'user-registration-trigger'
+     * );
+     *
+     * console.log('Trigger set for campaign:', updated.title);
+     * console.log('Trigger will activate on user registration');
+     * ```
      */
     setCampaignTrigger(campaignId: string, triggerId: string): Promise<CampaignDTO>;
     /**
      * Admin: Create campaign token unit
      *
-     * @param campaignId - ID of campaign
-     * @param tokenUnit - Token unit data
-     * @returns Promise resolving to updated campaign
+     * Adds a token reward unit to a campaign, specifying the token type and amount
+     * that users will receive when claiming the campaign. Multiple token units
+     * can be added to create multi-reward campaigns. Requires administrator privileges.
+     *
+     * @param campaignId - ID of the campaign
+     * @param tokenUnit - Token unit configuration including token type and amount
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or validation fails
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - add loyalty points reward
+     * const updated = await sdk.campaigns.createCampaignTokenUnit('summer-promo', {
+     *   tokenId: 'loyalty-points',
+     *   amount: 500,
+     *   type: 'REWARD'
+     * });
+     *
+     * console.log('Token unit added to campaign');
+     * console.log('Reward units:', updated.tokenUnits?.length);
+     *
+     * // Add multiple reward types
+     * await sdk.campaigns.createCampaignTokenUnit('summer-promo', {
+     *   tokenId: 'bonus-credits',
+     *   amount: 100,
+     *   type: 'BONUS'
+     * });
+     * ```
      */
     createCampaignTokenUnit(campaignId: string, tokenUnit: TokenUnitCreateRequestDTO): Promise<CampaignDTO>;
     /**
      * Admin: Delete campaign token unit
      *
-     * @param campaignId - ID of campaign
-     * @param tokenUnitId - ID of token unit to delete
-     * @returns Promise resolving to updated campaign
+     * Removes a token reward unit from a campaign. This affects future claims
+     * but does not impact rewards that have already been distributed. Requires
+     * administrator privileges.
+     *
+     * @param campaignId - ID of the campaign
+     * @param tokenUnitId - ID of the token unit to remove
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or entities not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - remove token unit from campaign
+     * const updated = await sdk.campaigns.deleteCampaignTokenUnit(
+     *   'summer-promo',
+     *   'token-unit-123'
+     * );
+     *
+     * console.log('Token unit removed from campaign');
+     * console.log('Remaining reward units:', updated.tokenUnits?.length);
+     * ```
      */
     deleteCampaignTokenUnit(campaignId: string, tokenUnitId: string): Promise<CampaignDTO>;
     /**
      * Admin: Add business engagement to campaign
      *
-     * @param campaignId - ID of campaign
-     * @param engagement - Business engagement data
-     * @returns Promise resolving to updated campaign
+     * Associates a business partner with a campaign, enabling the business to
+     * participate in the campaign and allowing users to claim rewards through
+     * that business. Requires administrator privileges.
+     *
+     * @param campaignId - ID of the campaign
+     * @param engagement - Business engagement configuration
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or validation fails
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - add business partner to campaign
+     * const updated = await sdk.campaigns.addBusinessEngagementToCampaign('summer-promo', {
+     *   businessId: 'partner-hotel-123',
+     *   engagementType: 'PROMOTION_PARTNER',
+     *   isActive: true,
+     *   startDate: '2024-06-01',
+     *   endDate: '2024-08-31'
+     * });
+     *
+     * console.log('Business partner added to campaign');
+     * console.log('Partner businesses:', updated.businessEngagements?.length);
+     * ```
      */
     addBusinessEngagementToCampaign(campaignId: string, engagement: CampaignBusinessEngagementCreateRequestDTO): Promise<CampaignDTO>;
     /**
      * Admin: Update campaign business engagement
      *
-     * @param campaignId - ID of campaign
-     * @param engagementId - ID of engagement to update
-     * @param engagement - Updated engagement data
-     * @returns Promise resolving to updated campaign
+     * Updates an existing business engagement within a campaign, modifying
+     * participation parameters, dates, or status. Requires administrator privileges.
+     *
+     * @param campaignId - ID of the campaign
+     * @param engagementId - ID of the engagement to update
+     * @param engagement - Updated engagement configuration
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or entities not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - update business engagement terms
+     * const updated = await sdk.campaigns.updateCampaignBusinessEngagement(
+     *   'summer-promo',
+     *   'engagement-456',
+     *   {
+     *     engagementType: 'PREMIUM_PARTNER',
+     *     isActive: true,
+     *     endDate: '2024-09-30'  // Extended participation
+     *   }
+     * );
+     *
+     * console.log('Business engagement updated');
+     * ```
      */
     updateCampaignBusinessEngagement(campaignId: string, engagementId: string, engagement: CampaignBusinessEngagementCreateRequestDTO): Promise<CampaignDTO>;
     /**
      * Admin: Delete campaign business engagement
      *
-     * @param campaignId - ID of campaign
-     * @param engagementId - ID of engagement to delete
-     * @returns Promise resolving to updated campaign
+     * Removes a business engagement from a campaign, ending the business's
+     * participation in the campaign. Existing claims through this business
+     * remain valid. Requires administrator privileges.
+     *
+     * @param campaignId - ID of the campaign
+     * @param engagementId - ID of the engagement to remove
+     * @returns Promise resolving to updated campaign data
+     * @throws {PersApiError} When not authenticated as admin or entities not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - remove business from campaign
+     * const updated = await sdk.campaigns.deleteCampaignBusinessEngagement(
+     *   'summer-promo',
+     *   'engagement-456'
+     * );
+     *
+     * console.log('Business engagement removed');
+     * console.log('Remaining partners:', updated.businessEngagements?.length);
+     * ```
      */
     deleteCampaignBusinessEngagement(campaignId: string, engagementId: string): Promise<CampaignDTO>;
     /**
      * Admin: Get all campaign claims
      *
-     * @returns Promise resolving to array of campaign claims
+     * Retrieves all campaign claims across the system for comprehensive reporting
+     * and analytics. This operation requires administrator privileges and provides
+     * system-wide visibility into campaign performance and user engagement.
+     *
+     * @returns Promise resolving to array of all campaign claims
+     * @throws {PersApiError} When not authenticated as administrator
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - get campaign performance data
+     * const allClaims = await sdk.campaigns.getCampaignClaims();
+     *
+     * console.log(`📊 Campaign Performance Report:`);
+     * console.log(`Total claims: ${allClaims.length}`);
+     *
+     * // Analyze claims by campaign
+     * const claimsByCampaign = allClaims.reduce((acc, claim) => {
+     *   const campaignId = claim.campaignId;
+     *   acc[campaignId] = (acc[campaignId] || 0) + 1;
+     *   return acc;
+     * }, {});
+     *
+     * console.log('\nClaims by Campaign:');
+     * Object.entries(claimsByCampaign).forEach(([campaignId, count]) => {
+     *   console.log(`${campaignId}: ${count} claims`);
+     * });
+     * ```
      */
     getCampaignClaims(): Promise<CampaignClaimDTO[]>;
     /**
      * Admin: Get campaign claims by user ID
      *
-     * @param userId - ID of user
+     * Retrieves all campaign claims for a specific user. This operation requires
+     * administrator privileges and is used for user support, account analysis,
+     * and individual user engagement tracking.
+     *
+     * @param userId - ID of the user to get claims for
      * @returns Promise resolving to array of user's campaign claims
+     * @throws {PersApiError} When not authenticated as admin or user not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - analyze user's campaign participation
+     * const userClaims = await sdk.campaigns.getCampaignClaimsByUserId('user-123');
+     *
+     * console.log(`User Campaign Activity:`);
+     * console.log(`Total campaigns claimed: ${userClaims.length}`);
+     *
+     * userClaims.forEach((claim, index) => {
+     *   console.log(`\n${index + 1}. ${claim.campaign.title}`);
+     *   console.log(`   Date: ${claim.claimedAt}`);
+     *   console.log(`   Business: ${claim.business?.displayName || 'Direct'}`);
+     *   console.log(`   Rewards: ${claim.rewards?.length || 0} items`);
+     * });
+     *
+     * // Calculate user engagement metrics
+     * const totalRewards = userClaims.reduce((sum, claim) =>
+     *   sum + (claim.rewards?.length || 0), 0
+     * );
+     * console.log(`\nTotal rewards earned: ${totalRewards}`);
+     * ```
      */
     getCampaignClaimsByUserId(userId: string): Promise<CampaignClaimDTO[]>;
     /**
      * Admin: Get campaign claims by business ID
      *
-     * @param businessId - ID of business
+     * Retrieves all campaign claims processed through a specific business partner.
+     * This operation requires administrator privileges and is used for business
+     * partnership analysis and performance tracking.
+     *
+     * @param businessId - ID of the business to get claims for
      * @returns Promise resolving to array of business's campaign claims
+     * @throws {PersApiError} When not authenticated as admin or business not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - analyze business partnership performance
+     * const businessClaims = await sdk.campaigns.getCampaignClaimsByBusinessId('partner-hotel-123');
+     *
+     * console.log(`Business Partnership Analysis:`);
+     * console.log(`Claims processed: ${businessClaims.length}`);
+     *
+     * // Analyze claims by campaign
+     * const claimsByCampaign = businessClaims.reduce((acc, claim) => {
+     *   const title = claim.campaign.title;
+     *   acc[title] = (acc[title] || 0) + 1;
+     *   return acc;
+     * }, {});
+     *
+     * console.log('\nCampaign Performance:');
+     * Object.entries(claimsByCampaign).forEach(([campaign, count]) => {
+     *   console.log(`${campaign}: ${count} claims`);
+     * });
+     *
+     * // Calculate partnership value
+     * const totalRewardsDistributed = businessClaims.reduce((sum, claim) =>
+     *   sum + (claim.rewards?.length || 0), 0
+     * );
+     * console.log(`\nTotal rewards distributed: ${totalRewardsDistributed}`);
+     * ```
      */
     getCampaignClaimsByBusinessId(businessId: string): Promise<CampaignClaimDTO[]>;
     /**
-     * Get the full campaign SDK for advanced operations
+     * Get the full campaign service for advanced operations
+     *
+     * Provides access to the complete CampaignService instance for advanced campaign
+     * operations, custom triggers, analytics, and operations not covered by the
+     * high-level manager methods.
+     *
+     * @returns CampaignService instance with full API access
+     *
+     * @example Advanced Operations
+     * ```typescript
+     * const campaignService = sdk.campaigns.getCampaignService();
+     *
+     * // Access advanced campaign analytics
+     * const analytics = await campaignService.getCampaignAnalytics('campaign-123');
+     *
+     * // Access custom trigger management
+     * const customTriggers = await campaignService.getCustomTriggers();
+     *
+     * // Access campaign API directly
+     * const campaignApi = campaignService.api;
      *
-     * @returns CampaignSDK instance
+     * // Use advanced claim validation
+     * const eligibility = await campaignService.validateClaimEligibility('user-123', 'campaign-456');
+     * ```
      */
-    getCampaignSDK(): CampaignSDK;
+    getCampaignService(): CampaignService;
 }
 //# sourceMappingURL=campaign-manager.d.ts.map