@explorins/pers-sdk 1.0.0-alpha.1 → 1.1.2

package/src/payment/api/payment-api.ts

@@ -0,0 +1,185 @@
+import { PersApiClient } from '../../core/pers-api-client';
+import { 
+  PurchaseTokenDTO,
+  PurchaseDTO,
+  PurchaseCurrency,
+  PurchaseCreateRequestDTO,
+  PaymentIntentDTO,
+  PaymentIntentCreateDTO,
+  PurchaseCreateResponseDTO,
+  DonationTypeDTO
+} from '../models';
+
+/**
+ * Platform-Agnostic Purchase API Client (RESTful Architecture)
+ * 
+ * Handles purchase and payment operations using the PERS backend's new RESTful endpoints.
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ * 
+ * Migration Status: Updated to match /purchases controller (replaces /purchase endpoints)
+ * 
+ * Available Access Levels:
+ * - PUBLIC: Project key authentication for catalog browsing and payment operations
+ * - USER: Requires user authentication JWT (purchase creation, history access)
+ * - ADMIN: Requires tenant admin privileges (not implemented in this client)
+ * 
+ * Note: This SDK focuses on backend purchase operations only.
+ * Payment provider integrations (Stripe, etc.) should remain in infrastructure layer.
+ */
+export class PurchaseApi {
+  constructor(private apiClient: PersApiClient) {}
+
+  private readonly basePath = '/purchases';
+
+  // ==========================================
+  // PUBLIC OPERATIONS (Project Key)
+  // ==========================================
+
+  /**
+   * PUBLIC: Get purchase tokens (Intelligent Access)
+   * 
+   * RESTful endpoint: GET /purchases/tokens
+   * Replaces: GET /purchase/token
+   * 
+   * INTELLIGENT ACCESS:
+   * - PUBLIC (Project Key): Returns active tokens only (active parameter ignored)
+   * - ADMIN (Tenant Admin JWT): Returns filtered results based on active parameter
+   */
+  async getPurchaseTokens(active?: boolean): Promise<PurchaseTokenDTO[]> {
+    let url = `${this.basePath}/tokens`;
+    if (active !== undefined) {
+      url += `?active=${active}`;
+    }
+    return this.apiClient.get<PurchaseTokenDTO[]>(url);
+  }
+
+  /**
+   * PUBLIC: Get donation types
+   * 
+   * RESTful endpoint: GET /purchases/donation-types
+   * Replaces: GET /purchase/donation/type
+   */
+  async getDonationTypes(): Promise<DonationTypeDTO[]> {
+    return this.apiClient.get<DonationTypeDTO[]>(`${this.basePath}/donation-types`);
+  }
+
+  // ==========================================
+  // PAYMENT OPERATIONS (FINANCIAL - CRITICAL)
+  // ==========================================
+
+  /**
+   * PUBLIC: Create payment intent (FINANCIAL OPERATION)
+   * 
+   * RESTful endpoint: POST /purchases/payment-intents
+   * Replaces: POST /purchase/payment-intent
+   * 
+   * CRITICAL: Handles real money operations - tenant context required
+   */
+  async createPaymentIntent(amount: number, currency: PurchaseCurrency, receiptEmail: string, description: string): Promise<PaymentIntentDTO> {
+    const body: PaymentIntentCreateDTO = {
+      amount,
+      currency,
+      receiptEmail,
+      description
+    };
+    return this.apiClient.post<PaymentIntentDTO>(`${this.basePath}/payment-intents`, body);
+  }
+
+  /**
+   * PUBLIC: Update payment intent (FINANCIAL OPERATION)
+   * 
+   * RESTful endpoint: PUT /purchases/payment-intents/{paymentIntentId}
+   * Replaces: PUT /purchase/payment-intent/{paymentIntentId}
+   * 
+   * CRITICAL: Handles real money operations - tenant context required
+   */
+  async updatePaymentIntent(paymentIntentId: string, amount: number, currency: PurchaseCurrency, receiptEmail: string, description: string): Promise<PaymentIntentDTO> {
+    const body: PaymentIntentCreateDTO = {
+      amount,
+      currency,
+      receiptEmail,
+      description
+    };
+    return this.apiClient.put<PaymentIntentDTO>(`${this.basePath}/payment-intents/${paymentIntentId}`, body);
+  }
+
+  /**
+   * PUBLIC: Cancel payment intent (FINANCIAL OPERATION)
+   * 
+   * RESTful endpoint: DELETE /purchases/payment-intents/{paymentIntentId}
+   * Replaces: DELETE /purchase/payment-intent/{paymentIntentId}
+   * 
+   * CRITICAL: Handles real money operations - tenant context required
+   */
+  async cancelPaymentIntent(paymentIntentId: string): Promise<PaymentIntentDTO> {
+    return this.apiClient.delete<PaymentIntentDTO>(`${this.basePath}/payment-intents/${paymentIntentId}`);
+  }
+
+  // ==========================================
+  // USER OPERATIONS (JWT + Project Key)
+  // ==========================================
+
+  /**
+   * USER: Create purchase (BUSINESS CRITICAL - FINANCIAL TRANSACTION)
+   * 
+   * RESTful endpoint: POST /purchases
+   * Replaces: POST /purchase/auth
+   * 
+   * USER-ONLY: Requires user authentication JWT for purchase creation
+   * CRITICAL: Real financial transaction with Stripe integration
+   */
+  async createUserPurchase(paymentIntentId: string, amount: number, purchaseTokenId?: string, donationTypeId?: number, donationAccountAddress?: string): Promise<PurchaseCreateResponseDTO> {
+    const body: PurchaseCreateRequestDTO = {
+      quantity: amount,
+      purchaseTokenId: purchaseTokenId || '',
+      donationTypeId,
+      donationAccountAddress,
+      paymentIntentId
+    };
+    return this.apiClient.post<PurchaseCreateResponseDTO>(`${this.basePath}`, body);
+  }
+
+  /**
+   * USER: Get user purchase history
+   * 
+   * RESTful endpoint: GET /purchases/me/history
+   * Replaces: GET /purchase/auth
+   * 
+   * USER-ONLY: Get authenticated user's purchase history
+   * FINANCIAL RECORDS: User attribution critical for compliance
+   */
+  async getUserPurchaseHistory(): Promise<PurchaseDTO[]> {
+    return this.apiClient.get<PurchaseDTO[]>(`${this.basePath}/me/history`);
+  }
+
+  // ==========================================
+  // CONVENIENCE METHODS (Backward Compatibility)
+  // ==========================================
+
+  /**
+   * @deprecated Use getPurchaseTokens() instead
+   * Backward compatibility alias for getActivePurchaseTokens
+   */
+  async getActivePurchaseTokens(active: boolean = true): Promise<PurchaseTokenDTO[]> {
+    return this.getPurchaseTokens(active);
+  }
+
+  /**
+   * @deprecated Use createUserPurchase() instead
+   * Backward compatibility alias for createPurchase
+   */
+  async createPurchase(paymentIntentId: string, amount: number, purchaseTokenId?: string, donationTypeId?: number, donationAccountAddress?: string): Promise<PurchaseCreateResponseDTO> {
+    return this.createUserPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress);
+  }
+
+  /**
+   * @deprecated Use getUserPurchaseHistory() instead
+   * Backward compatibility alias for getAllUserPurchases
+   */
+  async getAllUserPurchases(): Promise<PurchaseDTO[]> {
+    return this.getUserPurchaseHistory();
+  }
+}
+
+// Backward compatibility - export as PaymentApi as well
+export { PurchaseApi as PaymentApi };

package/src/payment/index.ts

@@ -0,0 +1,64 @@
+/**
+ * @explorins/pers-sdk-payment
+ * 
+ * Platform-agnostic Payment Domain SDK for PERS ecosystem
+ * Handles payment intents, purchases, and purchase tokens
+ * 
+ * Note: Payment provider integrations (Stripe, etc.) are kept separate
+ * in the infrastructure layer to maintain platform-agnostic principles.
+ */
+
+// API Layer
+export { PaymentApi } from './api/payment-api';
+
+// Service Layer  
+export { PaymentService } from './services/payment-service';
+
+// Models & Types
+export * from './models';
+export * from '../shared/interfaces/pers-shared-lib.interfaces';
+
+// Models & Types
+export * from './models';
+
+// Factory function for creating payment SDK instance
+import { PersApiClient } from '../core/pers-api-client';
+import { PaymentApi } from './api/payment-api';
+import { PurchaseCurrency } from './models';
+import { PaymentService } from './services/payment-service';
+
+/**
+ * Create a complete Payment SDK instance
+ * 
+ * @param apiClient - Configured PERS API client
+ * @returns Payment SDK with flattened structure for better DX
+ */
+export function createPaymentSDK(apiClient: PersApiClient) {
+  const paymentApi = new PaymentApi(apiClient);
+  const paymentService = new PaymentService(paymentApi);
+  
+  return {
+    // Direct access to service methods (primary interface)
+    
+    // Public methods
+    getActivePurchaseTokens: (active?: boolean) => paymentService.getActivePurchaseTokens(active),
+    // ✅ FIXED: Proper type instead of any
+    createPaymentIntent: (amount: number, currency: PurchaseCurrency, receiptEmail: string, description: string) => 
+      paymentService.createPaymentIntent(amount, currency, receiptEmail, description),
+    // ✅ FIXED: Proper type instead of any
+    updatePaymentIntent: (paymentIntentId: string, amount: number, currency: PurchaseCurrency, receiptEmail: string, description: string) => 
+      paymentService.updatePaymentIntent(paymentIntentId, amount, currency, receiptEmail, description),
+    cancelPaymentIntent: (paymentIntentId: string) => paymentService.cancelPaymentIntent(paymentIntentId),
+    
+    // Auth methods
+    createPurchase: (paymentIntentId: string, amount: number, purchaseTokenId?: string, donationTypeId?: number, donationAccountAddress?: string) => 
+      paymentService.createPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress),
+    getAllUserPurchases: () => paymentService.getAllUserPurchases(),
+    
+    // Advanced access for edge cases
+    api: paymentApi,
+    service: paymentService
+  };
+}
+
+export type PaymentSDK = ReturnType<typeof createPaymentSDK>;

package/src/payment/models/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Payment Domain Models
+ * 
+ * Re-exports from centralized pers-shared interfaces for consistency with backend
+ * and to provide a single import source for payment-related types.
+ */
+
+// Core payment entities from centralized pers-shared interfaces
+export type {
+  UserDTO,
+  PurchaseDTO,
+  PurchaseTokenDTO,
+  PurchaseTypeDTO,
+  PaymentIntentDTO,
+  PurchaseCreateRequestDTO,
+  PurchaseCreateResponseDTO,
+  PaymentIntentCreateDTO,
+  PurchaseCurrency,
+  DonationTypeDTO
+} from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+// Import for local interface usage
+import { PaymentIntentCreateDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+// Local payment interfaces
+export interface PaymentIntentUpdateDTO extends PaymentIntentCreateDTO {
+  paymentIntentId: string;
+}
+

package/src/payment/services/payment-service.ts

@@ -0,0 +1,70 @@
+import { PaymentApi } from '../api/payment-api';
+import { 
+  PurchaseTokenDTO,
+  PurchaseDTO,
+  PurchaseCurrency,
+  PaymentIntentDTO,
+} from '../models';
+
+/**
+ * Platform-Agnostic Payment Service
+ * 
+ * Contains payment business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * 
+ * Focuses only on actual backend capabilities.
+ * Payment provider logic (Stripe, etc.) should remain in infrastructure layer.
+ */
+export class PaymentService {
+  constructor(private paymentApi: PaymentApi) {}
+
+  // ==========================================
+  // PUBLIC OPERATIONS
+  // ==========================================
+
+  /**
+   * PUBLIC: Get active purchase tokens
+   */
+  async getActivePurchaseTokens(active: boolean = true): Promise<PurchaseTokenDTO[]> {
+    return this.paymentApi.getActivePurchaseTokens(active);
+  }
+
+  /**
+   * PUBLIC: Create payment intent
+   */
+  async createPaymentIntent(amount: number, currency: PurchaseCurrency, receiptEmail: string, description: string): Promise<PaymentIntentDTO> {
+    return this.paymentApi.createPaymentIntent(amount, currency, receiptEmail, description);
+  }
+
+  /**
+   * PUBLIC: Update payment intent
+   */
+  async updatePaymentIntent(paymentIntentId: string, amount: number, currency: PurchaseCurrency, receiptEmail: string, description: string): Promise<PaymentIntentDTO> {
+    return this.paymentApi.updatePaymentIntent(paymentIntentId, amount, currency, receiptEmail, description);
+  }
+
+  /**
+   * PUBLIC: Cancel payment intent
+   */
+  async cancelPaymentIntent(paymentIntentId: string): Promise<PaymentIntentDTO> {
+    return this.paymentApi.cancelPaymentIntent(paymentIntentId);
+  }
+
+  // ==========================================
+  // AUTHENTICATED OPERATIONS
+  // ==========================================
+
+  /**
+   * AUTH: Create purchase
+   */
+  async createPurchase(paymentIntentId: string, amount: number, purchaseTokenId?: string, donationTypeId?: number, donationAccountAddress?: string): Promise<PurchaseDTO> {
+    return this.paymentApi.createPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress);
+  }
+
+  /**
+   * AUTH: Get all user purchases
+   */
+  async getAllUserPurchases(): Promise<PurchaseDTO[]> {
+    return this.paymentApi.getAllUserPurchases();
+  }
+}

package/src/redemption/api/redemption-api.ts

@@ -0,0 +1,241 @@
+import { TokenUnitCreateRequestDTO, RedemptionTypeCreateRequestDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+import { PersApiClient } from '../../core/pers-api-client';
+import {
+  RedemptionDTO,
+  RedemptionCreateRequestDTO,
+  RedemptionRedeemRequestDTO,
+  RedemptionTypeDTO,
+  RedemptionUserRedeemDTO,
+  RedemptionUserRedeemDetailedDTO
+} from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+/**
+ * Platform-Agnostic Redemption API Client (UPDATED - RESTful Design)
+ * 
+ * Updated to work with the new RESTful /redemptions endpoints.
+ * Handles redemption operations using the PERS backend with intelligent access detection.
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ * 
+ * Migration Update: Updated all endpoints from /redemption to /redemptions
+ * - Removed role revelation from URLs (no more /admin, /auth paths)
+ * - Added intelligent access detection for unified endpoints
+ * - Updated toggle endpoint to follow /status pattern
+ * - Enhanced redemption process with path-based IDs
+ */
+export class RedemptionApi {
+  constructor(private apiClient: PersApiClient) {}
+
+  private readonly basePath = '/redemptions';
+
+  // ==========================================
+  // PUBLIC OPERATIONS (Project Key)
+  // ==========================================
+
+  /**
+   * PUBLIC: Get redemptions (intelligent access)
+   * 
+   * NEW: Intelligent endpoint that adapts based on authentication
+   * - Public users: Get active redemptions only
+   * - Admin users: Get all redemptions with optional filtering
+   * 
+   * Replaces: getActiveRedemptions() + getRedemptionsAsAdmin()
+   */
+  async getRedemptions(active?: boolean): Promise<RedemptionDTO[]> {
+    let url = `${this.basePath}`;
+    if (active !== undefined) {
+      url += `?active=${active}`;
+    }
+    return this.apiClient.get<RedemptionDTO[]>(url);
+  }
+
+  /**
+   * PUBLIC: Get active redemptions
+   * 
+   * Updated: Now uses unified endpoint (backward compatibility)
+   */
+  async getActiveRedemptions(): Promise<RedemptionDTO[]> {
+    return this.getRedemptions(); // Will return active only for public access
+  }
+
+  /**
+   * PUBLIC: Get redemption types
+   * 
+   * Updated: /redemption/type → /redemptions/types
+   */
+  async getRedemptionTypes(): Promise<RedemptionTypeDTO[]> {
+    return this.apiClient.get<RedemptionTypeDTO[]>(`${this.basePath}/types`);
+  }
+
+  /**
+   * PUBLIC: Get redemption by ID
+   * 
+   * Updated: /redemption/:id → /redemptions/:id
+   */
+  async getRedemptionById(id: string): Promise<RedemptionDTO> {
+    return this.apiClient.get<RedemptionDTO>(`${this.basePath}/${id}`);
+  }
+
+  /**
+   * PUBLIC: Get available supply for redemption
+   * 
+   * Updated: /redemption/:id/available-supply → /redemptions/:id/available-supply
+   */
+  async getRedemptionAvailableSupply(id: string): Promise<number> {
+    return this.apiClient.get<number>(`${this.basePath}/${id}/available-supply`);
+  }
+
+  // ==========================================
+  // USER OPERATIONS (JWT + Project Key)
+  // ==========================================
+
+  /**
+   * USER: Redeem a redemption
+   * 
+   * Updated: /redemption/auth/redeem → /redemptions/:id/redeem
+   * Enhanced: Path-based redemption ID for better RESTful design
+   */
+  async redeemRedemption(redemptionId: string): Promise<RedemptionUserRedeemDetailedDTO> {
+    const body: RedemptionRedeemRequestDTO = {
+      redemptionId: redemptionId,
+    };
+    return this.apiClient.post<RedemptionUserRedeemDetailedDTO>(`${this.basePath}/${redemptionId}/redeem`, body);
+  }
+
+  /**
+   * USER: Get user redemption history
+   * 
+   * Updated: /redemption/auth/redeem → /redemptions/me/history
+   */
+  async getUserRedemptionHistory(): Promise<RedemptionUserRedeemDTO[]> {
+    return this.apiClient.get<RedemptionUserRedeemDTO[]>(`${this.basePath}/me/history`);
+  }
+
+  /**
+   * USER: Get user redemptions (backward compatibility)
+   * 
+   * Deprecated: Use getUserRedemptionHistory() instead
+   */
+  async getUserRedeems(): Promise<RedemptionUserRedeemDTO[]> {
+    return this.getUserRedemptionHistory();
+  }
+
+  // ==========================================
+  // ADMIN OPERATIONS (Tenant Admin JWT)
+  // ==========================================
+
+  /**
+   * ADMIN: Get redemptions with filtering (using intelligent endpoint)
+   * 
+   * Updated: /redemption/admin → /redemptions (intelligent access detection)
+   * The unified endpoint will detect admin privileges and allow filtering
+   */
+  async getRedemptionsAsAdmin(active?: boolean): Promise<RedemptionDTO[]> {
+    return this.getRedemptions(active); // Uses intelligent endpoint
+  }
+
+  /**
+   * ADMIN: Create redemption
+   * 
+   * Updated: /redemption/admin → /redemptions
+   */
+  async createRedemption(redemption: RedemptionCreateRequestDTO): Promise<RedemptionDTO> {
+    return this.apiClient.post<RedemptionDTO>(`${this.basePath}`, redemption);
+  }
+
+  /**
+   * ADMIN: Update redemption
+   * 
+   * Updated: /redemption/admin/:id → /redemptions/:id
+   */
+  async updateRedemption(id: string, redemptionCreateRequest: RedemptionCreateRequestDTO): Promise<RedemptionDTO> {
+    return this.apiClient.put<RedemptionDTO>(`${this.basePath}/${id}`, redemptionCreateRequest);
+  }
+
+  /**
+   * ADMIN: Toggle redemption status
+   * 
+   * Updated: /redemption/admin/:id/toggle-active → /redemptions/:id/status
+   * Following standard /status pattern used across domains
+   */
+  async toggleRedemptionStatus(redemptionId: string): Promise<RedemptionDTO> {
+    return this.apiClient.put<RedemptionDTO>(`${this.basePath}/${redemptionId}/status`, {});
+  }
+
+  /**
+   * ADMIN: Toggle redemption active (backward compatibility)
+   * 
+   * Deprecated: Use toggleRedemptionStatus() instead
+   */
+  async toggleRedemptionActive(redemptionId: string): Promise<RedemptionDTO> {
+    return this.toggleRedemptionStatus(redemptionId);
+  }
+
+  /**
+   * ADMIN: Delete redemption
+   * 
+   * Updated: /redemption/admin/:id → /redemptions/:id
+   */
+  async deleteRedemption(id: string): Promise<boolean> {
+    return this.apiClient.delete<boolean>(`${this.basePath}/${id}`);
+  }
+
+  /**
+   * ADMIN: Create redemption type
+   * 
+   * Updated: /redemption/admin/type → /redemptions/types
+   */
+  async createRedemptionType(redemptionType: RedemptionTypeCreateRequestDTO): Promise<RedemptionTypeDTO> {
+    return this.apiClient.post<RedemptionTypeDTO>(`${this.basePath}/types`, redemptionType);
+  }
+
+  // ==========================================
+  // TOKEN UNIT MANAGEMENT (Admin)
+  // ==========================================
+
+  /**
+   * ADMIN: Create redemption token unit
+   * 
+   * Updated: /redemption/admin/:id/token-units → /redemptions/:id/token-units
+   */
+  async createRedemptionTokenUnit(redemptionId: string, redemptionTokenUnit: TokenUnitCreateRequestDTO): Promise<RedemptionDTO> {
+    return this.apiClient.post<RedemptionDTO>(`${this.basePath}/${redemptionId}/token-units`, redemptionTokenUnit);
+  }
+
+  /**
+   * ADMIN: Update redemption token unit
+   * 
+   * Updated: /redemption/admin/:id/token-units/:tokenUnitId → /redemptions/:id/token-units/:tokenUnitId
+   */
+  async updateRedemptionTokenUnit(redemptionId: string, tokenUnitId: string, redemptionTokenUnit: TokenUnitCreateRequestDTO): Promise<RedemptionDTO> {
+    return this.apiClient.put<RedemptionDTO>(`${this.basePath}/${redemptionId}/token-units/${tokenUnitId}`, redemptionTokenUnit);
+  }
+
+  /**
+   * ADMIN: Delete redemption token unit
+   * 
+   * Updated: /redemption/admin/:id/token-units/:tokenUnitId → /redemptions/:id/token-units/:tokenUnitId
+   */
+  async deleteRedemptionTokenUnit(redemptionId: string, redemptionTokenUnitId: string): Promise<RedemptionDTO> {
+    return this.apiClient.delete<RedemptionDTO>(`${this.basePath}/${redemptionId}/token-units/${redemptionTokenUnitId}`);
+  }
+
+  // ==========================================
+  // BACKWARD COMPATIBILITY METHODS
+  // ==========================================
+
+  /**
+   * @deprecated Use getRedemptions() instead
+   * Backward compatibility for old admin endpoint
+   */
+  async getRedemptionsAdmin(active?: boolean): Promise<RedemptionDTO[]> {
+    return this.getRedemptionsAsAdmin(active);
+  }
+
+  /**
+   * @deprecated Use redeemRedemption() instead  
+   * Backward compatibility for old redeem method
+   */
+  async redeem(redemptionId: string): Promise<RedemptionUserRedeemDetailedDTO> {
+    return this.redeemRedemption(redemptionId);
+  }
+}

package/src/redemption/index.ts

@@ -0,0 +1,60 @@
+/**
+ * @explorins/pers-sdk-redemption
+ * 
+ * Platform-agnostic Redemption Domain SDK for PERS ecosystem
+ * Handles redemption operations across different authorization levels
+ */
+
+// API Layer
+export { RedemptionApi } from './api/redemption-api';
+
+// Service Layer  
+export { RedemptionService } from './services/redemption-service';
+
+// Models & Types - re-export all centralized interfaces
+export * from '../shared/interfaces/pers-shared-lib.interfaces';
+
+// Models & Types - imported from centralized interfaces
+
+import { RedemptionCreateRequestDTO, TokenUnitCreateRequestDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
+// Factory function for creating redemption SDK instance
+import { PersApiClient } from '../core/pers-api-client';
+import { RedemptionApi } from './api/redemption-api';
+import { RedemptionService } from './services/redemption-service';
+
+/**
+ * Create a complete Redemption SDK instance
+ * 
+ * @param apiClient - Configured PERS API client
+ * @returns Redemption SDK with flattened structure for better DX
+ */
+export function createRedemptionSDK(apiClient: PersApiClient) {
+  const redemptionApi = new RedemptionApi(apiClient);
+  const redemptionService = new RedemptionService(redemptionApi);
+  
+  return {
+    // Direct access to service methods (primary interface)
+    
+    // Public methods
+    getActiveRedemptions: () => redemptionService.getActiveRedemptions(),
+    getRedemptionTypes: () => redemptionService.getRedemptionTypes(),
+    
+    // Auth methods
+    redeemRedemption: (redemptionId: string) => redemptionService.redeemRedemption(redemptionId),
+    getUserRedeems: () => redemptionService.getUserRedeems(),
+    
+    // Admin methods
+    getRedemptionsAsAdmin: (active?: boolean) => redemptionService.getRedemptionsAsAdmin(active),
+    createRedemption: (redemption: RedemptionCreateRequestDTO) => redemptionService.createRedemption(redemption),
+    updateRedemption: (id: string, redemptionCreateRequest: RedemptionCreateRequestDTO) => redemptionService.updateRedemption(id, redemptionCreateRequest),
+    toggleRedemptionActive: (redemptionId: string) => redemptionService.toggleRedemptionActive(redemptionId),
+    createRedemptionTokenUnit: (redemptionId: string, redemptionTokenUnit: TokenUnitCreateRequestDTO) => redemptionService.createRedemptionTokenUnit(redemptionId, redemptionTokenUnit),
+    deleteRedemptionTokenUnit: (redemptionId: string, redemptionTokenUnitId: string) => redemptionService.deleteRedemptionTokenUnit(redemptionId, redemptionTokenUnitId),
+    
+    // Advanced access for edge cases
+    api: redemptionApi,
+    service: redemptionService
+  };
+}
+
+export type RedemptionSDK = ReturnType<typeof createRedemptionSDK>;

package/src/redemption/models/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Redemption Domain Models
+ * 
+ * Re-exports from centralized pers-shared interfaces for consistency with backend
+ * and to provide a single import source for redemption-related types.
+ */
+
+// Core redemption entities from centralized pers-shared interfaces
+export type {
+  RedemptionDTO,
+  RedemptionCreateRequestDTO,
+  RedemptionRedeemRequestDTO,
+  RedemptionTypeDTO,
+  RedemptionTypeCreateRequestDTO,
+  RedemptionUserRedeemDTO,
+  RedemptionUserRedeemDetailedDTO
+} from '../../shared/interfaces/pers-shared-lib.interfaces';