@explorins/pers-sdk 1.6.45 → 2.0.0

package/README.md

@@ -16,11 +16,20 @@ Platform-agnostic TypeScript SDK for PERS (Phygital Experience Rewards System) -
 - [Platform Integration](#platform-integration)
 - [Architecture](#architecture)
 - [Core Features](#core-features)
+  - [Event System](#event-system)
+  - [Authentication](#authentication)
+  - [Business Management](#business-management)
+  - [Campaign System](#campaign-system)
+  - [Token Management](#token-management)
+  - [User Token Balances](#user-token-balances-on-chain)
+  - [Transaction Request Building](#transaction-request-building)
+  - [Purchase/Payment Processing](#purchasepayment-processing)
 - [Configuration](#configuration)
 - [Advanced Authentication](#advanced-authentication)
 - [Error Handling](#error-handling)
 - [Bundle Size](#bundle-size)
 - [TypeScript Types](#typescript-types)
+- [Migration Guide](#migration-guide)
 - [Documentation](#documentation)
 - [Related Packages](#related-packages)
 - [License](#license)
@@ -332,6 +341,85 @@ await apiClient.post('/custom-endpoint', { data: 'value' });
 
 ## Core Features
 
+### Event System
+
+The SDK provides a platform-agnostic event system for subscribing to SDK-wide events. All events have a `userMessage` field ready for UI display.
+
+```typescript
+// Subscribe to ALL events - one handler
+const unsubscribe = sdk.events.subscribe((event) => {
+  showNotification(event.userMessage, event.level);
+});
+
+// Filter by domain and level
+sdk.events.subscribe((event) => {
+  logToSentry(event);
+}, { level: 'error' });
+
+// Only transaction successes
+sdk.events.subscribe((event) => {
+  playSuccessSound();
+  confetti();
+}, { domain: 'transaction', level: 'success' });
+
+// One-time event (auto-unsubscribe)
+sdk.events.once((event) => {
+  console.log('First event:', event.type);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+#### Event Domains
+
+| Domain | Manager | Events |
+|--------|---------|--------|
+| `authentication` | `sdk.auth` | `LOGIN_SUCCESS` |
+| `user` | `sdk.users` | `PROFILE_UPDATED` |
+| `business` | `sdk.businesses` | `BUSINESS_CREATED`, `BUSINESS_UPDATED`, `MEMBERSHIP_UPDATED` |
+| `campaign` | `sdk.campaigns` | `CAMPAIGN_CLAIMED` |
+| `redemption` | `sdk.redemptions` | `REDEMPTION_COMPLETED` |
+| `transaction` | `sdk.transactions` | `TRANSACTION_CREATED`, `TRANSACTION_SUBMITTED` |
+
+#### Event Types
+
+```typescript
+import type { 
+  PersEvent,      // Base event type (discriminated union)
+  SuccessEvent,   // Success events (business domains)
+  ErrorEvent,     // Error events (all domains including technical)
+  EventFilter,    // Filter for subscriptions
+  EventHandler    // Handler type (sync or async)
+} from '@explorins/pers-sdk/core';
+
+// Event structure
+interface PersEvent {
+  id: string;           // Unique event ID
+  timestamp: number;    // Unix timestamp (ms)
+  domain: string;       // Event domain
+  type: string;         // Event type within domain
+  level: 'success' | 'error';
+  userMessage: string;  // Ready for UI display
+  action?: string;      // Suggested action
+  code?: string;        // Backend error code
+  details?: object;     // Additional data for logging
+}
+```
+
+#### Async Handler Support
+
+Event handlers can be synchronous or asynchronous. Async errors are caught automatically:
+
+```typescript
+sdk.events.subscribe(async (event) => {
+  await saveToDatabase(event);  // Async operations supported
+  await sendAnalytics(event);
+});
+```
+
+---
+
 ### Authentication
 
 The SDK uses **external JWT tokens** for authentication. You provide a JWT from your authentication provider (Firebase, Auth0, Cognito, etc.), and the SDK exchanges it for PERS access tokens.
@@ -538,6 +626,104 @@ async function loadUserTokenBalances(sdk: PersSDK) {
 }
 ```
 
+### Transaction Request Building
+
+The SDK provides factory functions for building transaction request DTOs. These are tree-shakeable and provide type-safe transaction creation:
+
+```typescript
+import { 
+  buildMintRequest, 
+  buildBurnRequest, 
+  buildTransferRequest,
+  buildPOSTransferRequest,
+  buildSubmissionRequest 
+} from '@explorins/pers-sdk/transaction';
+import { AccountOwnerType } from '@explorins/pers-shared';
+
+// Mint tokens to a recipient
+const mintRequest = buildMintRequest({
+  amount: 100,
+  contractAddress: '0x...',
+  chainId: 137,
+  recipientAccountId: 'user-123',
+  recipientAccountType: AccountOwnerType.USER
+});
+
+// Burn tokens
+const burnRequest = buildBurnRequest({
+  amount: 50,
+  contractAddress: '0x...',
+  chainId: 137,
+  senderAccountId: 'user-123',
+  senderAccountType: AccountOwnerType.USER
+});
+
+// Transfer tokens between accounts
+const transferRequest = buildTransferRequest({
+  amount: 100,
+  contractAddress: '0x...',
+  chainId: 137,
+  senderAccountId: 'user-123',
+  senderAccountType: AccountOwnerType.USER,
+  recipientAccountId: 'business-456',
+  recipientAccountType: AccountOwnerType.BUSINESS
+});
+
+// Submit the transaction
+const result = await sdk.transactions.createTransaction(mintRequest);
+```
+
+#### POS Transaction Flow
+
+For Point-of-Sale scenarios where a **business submits a transaction on behalf of a user**, use `buildPOSTransferRequest`:
+
+```typescript
+import { buildPOSTransferRequest } from '@explorins/pers-sdk/transaction';
+
+// POS flow: User pays business, business authorized to submit
+const posRequest = buildPOSTransferRequest({
+  amount: 100,
+  contractAddress: '0x...',
+  chainId: 137,
+  userAccountId: 'user-123',      // User sending tokens
+  businessAccountId: 'business-456' // Business receiving & authorized to submit
+});
+
+// This automatically sets:
+// - engagedBusinessId: 'business-456' (for reporting)
+// - authorizedSubmitterId: 'business-456' (can submit the signed tx)
+// - authorizedSubmitterType: AccountOwnerType.BUSINESS
+
+const result = await sdk.transactions.createTransaction(posRequest);
+```
+
+For custom authorization scenarios, use `buildTransferRequest` with manual POS fields:
+
+```typescript
+import { buildTransferRequest, type POSAuthorizationOptions } from '@explorins/pers-sdk/transaction';
+
+const customPOSRequest = buildTransferRequest({
+  amount: 100,
+  contractAddress: '0x...',
+  chainId: 137,
+  senderAccountId: 'user-123',
+  senderAccountType: AccountOwnerType.USER,
+  recipientAccountId: 'business-456',
+  recipientAccountType: AccountOwnerType.BUSINESS,
+  // POS authorization fields
+  engagedBusinessId: 'business-456',
+  authorizedSubmitterId: 'business-456',
+  authorizedSubmitterType: AccountOwnerType.BUSINESS
+});
+```
+
+| POS Field | Type | Description |
+|-----------|------|-------------|
+| `engagedBusinessId` | `string` | Business commercially involved (for stats/reporting) |
+| `authorizedSubmitterId` | `string` | Entity authorized to submit the signed transaction |
+| `authorizedSubmitterType` | `AccountOwnerType` | Type of authorized submitter (`USER` or `BUSINESS`) |
+```
+
 ### Purchase/Payment Processing
 
 ```typescript
@@ -825,6 +1011,108 @@ const claim = await sdk.campaigns.claimCampaign(claimRequest);
 
 ---
 
+## Migration Guide
+
+### v2.0.0 Breaking Changes - Pagination
+
+**Version 2.0.0 introduces standardized pagination** across all list endpoints. Previously, endpoints returned raw arrays. Now they return `PaginatedResponseDTO<T>` with pagination metadata.
+
+#### What Changed
+
+All methods returning lists now return paginated responses:
+
+```typescript
+// ❌ OLD (v1.x) - Direct array
+const businesses: BusinessDTO[] = await sdk.businesses.getActiveBusinesses();
+
+// ✅ NEW (v2.x) - Paginated response
+const response: PaginatedResponseDTO<BusinessDTO> = await sdk.businesses.getActiveBusinesses();
+const businesses: BusinessDTO[] = response.data;
+```
+
+#### Affected Methods
+
+| Manager | Method | Return Type |
+|---------|--------|-------------|
+| `businesses` | `getActiveBusinesses()` | `PaginatedResponseDTO<BusinessDTO>` |
+| `businesses` | `getBusinessTypes()` | `PaginatedResponseDTO<BusinessTypeDTO>` |
+| `campaigns` | `getActiveCampaigns()` | `PaginatedResponseDTO<CampaignDTO>` |
+| `campaigns` | `getUserClaims()` | `PaginatedResponseDTO<CampaignClaimDTO>` |
+| `tokens` | `getTokens()` | `PaginatedResponseDTO<TokenDTO>` |
+| `tokens` | `getRewardTokens()` | `PaginatedResponseDTO<TokenDTO>` |
+| `tokens` | `getStatusTokens()` | `PaginatedResponseDTO<TokenDTO>` |
+| `redemptions` | `getRedemptions()` | `PaginatedResponseDTO<RedemptionDTO>` |
+| `redemptions` | `getUserRedemptions()` | `PaginatedResponseDTO<RedemptionDTO>` |
+| `transactions` | `getTransactionHistory()` | `PaginatedResponseDTO<TransactionDTO>` |
+| `purchases` | `getAllUserPurchases()` | `PaginatedResponseDTO<PurchaseDTO>` |
+| `purchases` | `getActivePurchaseTokens()` | `PaginatedResponseDTO<PurchaseTokenDTO>` |
+| `donations` | `getDonationTypes()` | `PaginatedResponseDTO<DonationTypeDTO>` |
+
+#### PaginatedResponseDTO Structure
+
+```typescript
+import type { PaginatedResponseDTO } from '@explorins/pers-shared';
+
+interface PaginatedResponseDTO<T> {
+  data: T[];              // Array of results
+  pagination: {
+    currentPage: number;  // Current page number (1-indexed)
+    pageSize: number;     // Items per page
+    totalItems: number;   // Total number of items across all pages
+    totalPages: number;   // Total number of pages
+  };
+}
+```
+
+#### Migration Examples
+
+**Before (v1.x):**
+```typescript
+const businesses = await sdk.businesses.getActiveBusinesses();
+console.log('Business count:', businesses.length);
+businesses.forEach(b => console.log(b.name));
+```
+
+**After (v2.x):**
+```typescript
+const response = await sdk.businesses.getActiveBusinesses();
+console.log('Business count:', response.data.length);
+console.log('Total businesses:', response.pagination.totalItems);
+response.data.forEach(b => console.log(b.name));
+```
+
+**With Pagination Parameters:**
+```typescript
+// Fetch page 2 with 20 items per page
+const response = await sdk.businesses.getActiveBusinesses({
+  page: 2,
+  pageSize: 20
+});
+
+console.log(`Page ${response.pagination.currentPage} of ${response.pagination.totalPages}`);
+console.log(`Showing ${response.data.length} businesses`);
+```
+
+#### Quick Fix for Existing Code
+
+If you want minimal code changes, extract `.data` immediately:
+
+```typescript
+// Quick adaptation
+const businesses = (await sdk.businesses.getActiveBusinesses()).data;
+const campaigns = (await sdk.campaigns.getActiveCampaigns()).data;
+const tokens = (await sdk.tokens.getTokens()).data;
+```
+
+#### Benefits of Pagination
+
+- **Performance**: Load only what you need, not entire datasets
+- **Consistency**: All list endpoints follow the same pattern
+- **Metadata**: Access total counts without loading all items
+- **UX**: Build proper pagination UI components
+
+---
+
 ## Documentation
 
 - **Getting Started Guide**: [https://docs.pers.ninja/1.intro](https://docs.pers.ninja/1.intro)

package/dist/analytics.cjs

@@ -15,8 +15,20 @@ Object.defineProperty(exports, "ApiKeyType", {
 	enumerable: true,
 	get: function () { return persShared.ApiKeyType; }
 });
+Object.defineProperty(exports, "MEMBERSHIP_ROLE_HIERARCHY", {
+	enumerable: true,
+	get: function () { return persShared.MEMBERSHIP_ROLE_HIERARCHY; }
+});
+Object.defineProperty(exports, "MembershipRole", {
+	enumerable: true,
+	get: function () { return persShared.MembershipRole; }
+});
 Object.defineProperty(exports, "NativeTokenTypes", {
 	enumerable: true,
 	get: function () { return persShared.NativeTokenTypes; }
 });
+Object.defineProperty(exports, "hasMinimumRole", {
+	enumerable: true,
+	get: function () { return persShared.hasMinimumRole; }
+});
 //# sourceMappingURL=analytics.cjs.map

package/dist/analytics.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"analytics.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/analytics.js

@@ -1,3 +1,3 @@
 export { A as AnalyticsApi, a as AnalyticsService } from './chunks/analytics-service-CxyrOwel.js';
-export { AccountOwnerType, ApiKeyType, NativeTokenTypes } from '@explorins/pers-shared';
+export { AccountOwnerType, ApiKeyType, MEMBERSHIP_ROLE_HIERARCHY, MembershipRole, NativeTokenTypes, hasMinimumRole } from '@explorins/pers-shared';
 //# sourceMappingURL=analytics.js.map

package/dist/api-key/api/api-key-api.d.ts

@@ -1,5 +1,7 @@
 import { PersApiClient } from '../../core/pers-api-client';
 import { ApiKeyDTO, ApiKeyCreatedDTO, ApiKeyRequestDTO, ApiKeyVerificationDTO, IntegrationApiKeyType } from '../../shared/interfaces/pers-shared-lib.interfaces';
+import { PaginatedResponseDTO } from '@explorins/pers-shared';
+import { PaginationOptions } from '../../shared';
 /**
  * Platform-Agnostic API Key API Client
  *
@@ -15,9 +17,10 @@ export declare class ApiKeyApi {
      *
      * @param type Optional filter by integration API key type (database-stored tokens that can be revoked)
      * @param includeRevoked Include revoked API keys in results (default: false)
-     * @returns Array of API keys for the current tenant
+     * @param options Pagination options (page, limit, sortBy, sortOrder)
+     * @returns Paginated response with API keys for the current tenant
      */
-    getTenantApiKeys(type?: IntegrationApiKeyType, includeRevoked?: boolean): Promise<ApiKeyDTO[]>;
+    getTenantApiKeys(type?: IntegrationApiKeyType, includeRevoked?: boolean, options?: PaginationOptions): Promise<PaginatedResponseDTO<ApiKeyDTO>>;
     /**
      * ADMIN: Create new API key
      *

package/dist/api-key/api/api-key-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-key-api.d.ts","sourceRoot":"","sources":["../../../src/api-key/api/api-key-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,oDAAoD,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,SAAS;IAGR,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;gBAEpB,SAAS,EAAE,aAAa;IAE5C;;;;;;OAMG;IACG,gBAAgB,CAAC,IAAI,CAAC,EAAE,qBAAqB,EAAE,cAAc,GAAE,OAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAW3G;;;;;OAKG;IACG,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIpE;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAGrE"}
+{"version":3,"file":"api-key-api.d.ts","sourceRoot":"","sources":["../../../src/api-key/api/api-key-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAA6D,MAAM,cAAc,CAAC;AAE5G;;;;;GAKG;AACH,qBAAa,SAAS;IAGR,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;gBAEpB,SAAS,EAAE,aAAa;IAE5C;;;;;;;OAOG;IACG,gBAAgB,CAAC,IAAI,CAAC,EAAE,qBAAqB,EAAE,cAAc,GAAE,OAAe,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAS5J;;;;;OAKG;IACG,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIpE;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAGrE"}

package/dist/business/api/business-api.d.ts

@@ -1,5 +1,7 @@
 import { PersApiClient } from '../../core/pers-api-client';
 import { BusinessDTO, BusinessTypeDTO, BusinessUpdateRequestDTO, BusinessCreateRequestDTO, BusinessToggleActiveRequestDTO, BusinessApiKeyDTO, BusinessTokenBalancesDTO, BusinessTypeCreateRequestDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+import { PaginationOptions } from '../../shared/utils/pagination-utils';
+import { PaginatedResponseDTO, SortOrder } from '@explorins/pers-shared';
 /**
  * Platform-Agnostic Business API Client
  *
@@ -17,8 +19,11 @@ export declare class BusinessApi {
      *
      * Endpoint: GET /business-types
      * Auth: @ApiSecurity('projectKey')
+     *
+     * @param options Pagination options (page, limit, sortBy, sortOrder)
+     * @returns Paginated response with business types
      */
-    getBusinessTypes(): Promise<BusinessTypeDTO[]>;
+    getBusinessTypes(options?: PaginationOptions): Promise<PaginatedResponseDTO<BusinessTypeDTO>>;
     /**
      * ADMIN: Create business type
      *
@@ -48,25 +53,39 @@ export declare class BusinessApi {
      */
     getCurrentBusiness(): Promise<BusinessTokenBalancesDTO>;
     /**
-     * Get all businesses with role-based filtering
+     * Get all businesses with role-based filtering and pagination
      *
-     * Endpoint: GET /businesses?active={boolean}&sanitize={mode}
+     * Endpoint: GET /businesses?active={boolean}&sanitize={mode}&page={number}&limit={number}
      * Auth: @ApiSecurity('projectKey') (enhanced with role-based filtering)
+     *
      * Note:
      * - Project API Key users: Active businesses only (automatically filtered)
      * - Admin JWT users: Full access with all query parameters
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated list of businesses
+     *
+     * @example
+     * ```typescript
+     * // Get first page of active businesses
+     * const page1 = await businessApi.getBusinesses({ active: true });
+     *
+     * // Get all businesses (admin only) with pagination
+     * const page2 = await businessApi.getBusinesses({
+     *   page: 2,
+     *   limit: 25,
+     *   sanitize: 'soft'
+     * });
+     * ```
      */
     getBusinesses(options?: {
         active?: boolean;
         sanitize?: 'soft' | 'hard';
-    }): Promise<BusinessDTO[]>;
-    /**
-     * Get all active businesses (convenience method)
-     *
-     * Endpoint: GET /businesses
-     * Auth: @ApiSecurity('projectKey')
-     */
-    getActiveBusinesses(): Promise<BusinessDTO[]>;
+        page?: number;
+        limit?: number;
+        sortBy?: string;
+        sortOrder?: SortOrder;
+    }): Promise<PaginatedResponseDTO<BusinessDTO>>;
     /**
      * Get business by ID
      *

package/dist/business/api/business-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"business-api.d.ts","sourceRoot":"","sources":["../../../src/business/api/business-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,wBAAwB,EACxB,8BAA8B,EAC9B,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,EAC7B,MAAM,oDAAoD,CAAC;AAE5D;;;;;;GAMG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,aAAa;IAE5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuB;IAMzD;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAIpD;;;;;OAKG;IACG,kBAAkB,CAAC,GAAG,EAAE,4BAA4B,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrF;;;;;OAKG;IACG,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAIxE;;;;;OAKG;IACG,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQtD;;;;;OAKG;IACG,kBAAkB,IAAI,OAAO,CAAC,wBAAwB,CAAC;IAI7D;;;;;;;;OAQG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE;QAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KAC5B,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAiB1B;;;;;OAKG;IACG,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAInD;;;;;OAKG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/D;;;;;OAKG;IACG,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAQxE;;;;;;OAMG;IACG,cAAc,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC,iBAAiB,GAAG,wBAAwB,CAAC;IAI1G;;OAEG;IACG,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,wBAAwB,CAAC;IAQ7G;;;;;OAKG;IACG,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIlE;;;;;OAKG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,wBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC;IAI9F;;;;;OAKG;IACG,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,8BAA8B,GAAG,OAAO,CAAC,WAAW,CAAC;CAiBlG"}
+{"version":3,"file":"business-api.d.ts","sourceRoot":"","sources":["../../../src/business/api/business-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,wBAAwB,EACxB,8BAA8B,EAC9B,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,EAC7B,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAA6D,MAAM,qCAAqC,CAAC;AACnI,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEzE;;;;;;GAMG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,aAAa;IAE5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuB;IAMzD;;;;;;;;OAQG;IACG,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,oBAAoB,CAAC,eAAe,CAAC,CAAC;IAMnG;;;;;OAKG;IACG,kBAAkB,CAAC,GAAG,EAAE,4BAA4B,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrF;;;;;OAKG;IACG,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAIxE;;;;;OAKG;IACG,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQtD;;;;;OAKG;IACG,kBAAkB,IAAI,OAAO,CAAC,wBAAwB,CAAC;IAI7D;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE;QAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,SAAS,CAAC;KACvB,GAAG,OAAO,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAkB9C;;;;;OAKG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/D;;;;;OAKG;IACG,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAQxE;;;;;;OAMG;IACG,cAAc,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC,iBAAiB,GAAG,wBAAwB,CAAC;IAI1G;;OAEG;IACG,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,wBAAwB,CAAC;IAQ7G;;;;;OAKG;IACG,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIlE;;;;;OAKG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,wBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC;IAI9F;;;;;OAKG;IACG,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,8BAA8B,GAAG,OAAO,CAAC,WAAW,CAAC;CAiBlG"}

package/dist/business/api/business-membership-api.d.ts

@@ -0,0 +1,205 @@
+import { PersApiClient } from '../../core/pers-api-client';
+import { BusinessMembershipDTO, AddBusinessMemberRequestDTO, UpdateBusinessMembershipRequestDTO, MembershipRole } from '../../shared/interfaces/pers-shared-lib.interfaces';
+import { PaginatedResponseDTO, SortOrder } from '@explorins/pers-shared';
+/**
+ * Business Membership API Client
+ *
+ * Platform-agnostic API client for managing business memberships.
+ * Handles user access to businesses with role-based permissions.
+ *
+ * Base Path: /businesses/:businessId/members
+ *
+ * Required Headers:
+ * - Authorization: Bearer <business_jwt_token>
+ * - X-Project-Key: <project_key>
+ *
+ * @example
+ * ```typescript
+ * const membershipApi = new BusinessMembershipApi(apiClient);
+ *
+ * // List all members of a business
+ * const members = await membershipApi.getMembers('business-123');
+ *
+ * // Add a new member
+ * const newMember = await membershipApi.addMember('business-123', {
+ *   userId: 'user-456',
+ *   role: MembershipRole.EDITOR
+ * });
+ * ```
+ *
+ * @version 2.0.0
+ */
+export declare class BusinessMembershipApi {
+    private apiClient;
+    constructor(apiClient: PersApiClient);
+    /**
+     * Build the membership endpoint path for a business
+     */
+    private getMembersPath;
+    /**
+     * Build the membership endpoint path for a specific member
+     */
+    private getMemberPath;
+    /**
+     * List all members of a business with pagination
+     *
+     * Endpoint: GET /businesses/:businessId/members
+     * Min Role: VIEWER (any member can view)
+     *
+     * @param businessId - The business UUID
+     * @param options - Pagination and filter options
+     * @returns Paginated array of business memberships with user and role details
+     *
+     * @throws {AuthenticationError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - businessId in path doesn't match JWT's business
+     *
+     * @example
+     * ```typescript
+     * // Get first page of members
+     * const page1 = await membershipApi.getMembers('business-123');
+     * page1.data.forEach(m => console.log(`${m.userId}: ${m.role}`));
+     *
+     * // Filter by role
+     * const admins = await membershipApi.getMembers('business-123', {
+     *   role: MembershipRole.ADMIN,
+     *   page: 1,
+     *   limit: 50
+     * });
+     *
+     * // Paginate through all members
+     * const page2 = await membershipApi.getMembers('business-123', { page: 2 });
+     * ```
+     */
+    getMembers(businessId: string, options?: {
+        page?: number;
+        limit?: number;
+        role?: MembershipRole;
+        sortBy?: string;
+        sortOrder?: SortOrder;
+    }): Promise<PaginatedResponseDTO<BusinessMembershipDTO>>;
+    /**
+     * Add a member to a business
+     *
+     * Endpoint: POST /businesses/:businessId/members
+     * Min Role: ADMIN
+     *
+     * @param businessId - The business UUID
+     * @param request - The add member request with userId and optional role
+     * @returns The created business membership
+     *
+     * @throws {AuthenticationError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN or higher)
+     * @throws {PersApiError} 404 - User not found
+     * @throws {PersApiError} 409 - User is already a member
+     *
+     * @example
+     * ```typescript
+     * const newMember = await membershipApi.addMember('business-123', {
+     *   userId: 'user-456',
+     *   role: MembershipRole.EDITOR
+     * });
+     * ```
+     */
+    addMember(businessId: string, request: AddBusinessMemberRequestDTO): Promise<BusinessMembershipDTO>;
+    /**
+     * Add a member to a business with explicit parameters
+     *
+     * Convenience method that constructs the request DTO internally.
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to add
+     * @param role - The role to assign (defaults to VIEWER)
+     * @returns The created business membership
+     *
+     * @example
+     * ```typescript
+     * const member = await membershipApi.addMemberByUserId(
+     *   'business-123',
+     *   'user-456',
+     *   MembershipRole.EDITOR
+     * );
+     * ```
+     */
+    addMemberByUserId(businessId: string, userId: string, role?: MembershipRole): Promise<BusinessMembershipDTO>;
+    /**
+     * Update a member's role in a business
+     *
+     * Endpoint: PUT /businesses/:businessId/members/:userId
+     * Min Role: ADMIN
+     *
+     * Business Rules:
+     * - Cannot demote the last OWNER (must transfer ownership first)
+     * - Can only assign roles up to your own level (ADMIN cannot create OWNER)
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to update
+     * @param request - The update request with new role
+     * @returns The updated business membership
+     *
+     * @throws {AuthenticationError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN or higher)
+     * @throws {PersApiError} 404 - Membership not found
+     * @throws {PersApiError} 400 - Cannot demote last OWNER
+     *
+     * @example
+     * ```typescript
+     * const updated = await membershipApi.updateMemberRole(
+     *   'business-123',
+     *   'user-456',
+     *   { role: MembershipRole.ADMIN }
+     * );
+     * ```
+     */
+    updateMemberRole(businessId: string, userId: string, request: UpdateBusinessMembershipRequestDTO): Promise<BusinessMembershipDTO>;
+    /**
+     * Update a member's role with explicit parameters
+     *
+     * Convenience method that constructs the request DTO internally.
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to update
+     * @param role - The new role to assign
+     * @returns The updated business membership
+     *
+     * @example
+     * ```typescript
+     * const updated = await membershipApi.setMemberRole(
+     *   'business-123',
+     *   'user-456',
+     *   MembershipRole.ADMIN
+     * );
+     * ```
+     */
+    setMemberRole(businessId: string, userId: string, role: MembershipRole): Promise<BusinessMembershipDTO>;
+    /**
+     * Remove a member from a business
+     *
+     * Endpoint: DELETE /businesses/:businessId/members/:userId
+     * Min Role: ADMIN
+     *
+     * Business Rules:
+     * - Cannot remove the last OWNER
+     * - Cannot remove yourself (use leave endpoint or transfer ownership)
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to remove
+     * @returns Success confirmation
+     *
+     * @throws {AuthenticationError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN or higher)
+     * @throws {PersApiError} 404 - Membership not found
+     * @throws {PersApiError} 400 - Cannot remove last OWNER
+     *
+     * @example
+     * ```typescript
+     * const result = await membershipApi.removeMember('business-123', 'user-456');
+     * if (result.success) {
+     *   console.log('Member removed successfully');
+     * }
+     * ```
+     */
+    removeMember(businessId: string, userId: string): Promise<{
+        success: boolean;
+    }>;
+}
+//# sourceMappingURL=business-membership-api.d.ts.map

package/dist/business/api/business-membership-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"business-membership-api.d.ts","sourceRoot":"","sources":["../../../src/business/api/business-membership-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,kCAAkC,EAClC,cAAc,EACf,MAAM,oDAAoD,CAAC;AAE5D,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,qBAAqB;IACpB,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,aAAa;IAE5C;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,UAAU,CACd,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,SAAS,CAAC;KACvB,GACA,OAAO,CAAC,oBAAoB,CAAC,qBAAqB,CAAC,CAAC;IAkBvD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC;IAOjC;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAsC,GAC3C,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kCAAkC,GAC1C,OAAO,CAAC,qBAAqB,CAAC;IAOjC;;;;;;;;;;;;;;;;;;OAkBG;IACG,aAAa,CACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAKjC"}

package/dist/business/index.d.ts

@@ -5,6 +5,8 @@
  * Focuses on non-admin business operations
  */
 export { BusinessApi } from './api/business-api';
+export { BusinessMembershipApi } from './api/business-membership-api';
 export { BusinessService } from './services/business-service';
+export { BusinessMembershipService } from './services/business-membership-service';
 export * from '../shared/interfaces/pers-shared-lib.interfaces';
 //# sourceMappingURL=index.d.ts.map