@explorins/pers-sdk 2.1.42 → 2.2.0-alpha.1

package/dist/chunks/{pers-sdk-DxYmXQcW.js → pers-sdk-CBRtrG03.js}

@@ -1,4 +1,4 @@
-import { AccountOwnerType, MembershipRole, WebhookMethod, WebhookExecutionStatus } from '@explorins/pers-shared';
+import { AccountOwnerType, MembershipRole, WebhookMethod, WebhookExecutionStatus, validateAllFields, validateFieldValue } from '@explorins/pers-shared';
 import { i as isTokenExpired, d as decodeJwtPayload, e as getTokenTimeToLive, E as ErrorUtils, A as AuthenticationError, b as PersApiError } from './index--OssIds0.js';
 import { UserService, UserApi } from '../user.js';
 import { createUserStatusSDK } from '../user-status.js';
@@ -1585,7 +1585,7 @@ class DefaultAuthProvider {
 /** SDK package name */
 const SDK_NAME = "@explorins/pers-sdk";
 /** SDK version - injected from package.json at build time */
-const SDK_VERSION = "2.1.42";
+const SDK_VERSION = "2.2.0-alpha.1";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -10106,6 +10106,429 @@ class WalletEventsManager {
     }
 }
 
+/**
+ * Custom Field Definitions API
+ *
+ * Low-level API for custom field definition CRUD operations.
+ * Used internally by CustomFieldDefinitionManager.
+ *
+ * @internal
+ */
+class CustomFieldApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/custom-field-definitions';
+    }
+    /**
+     * List all custom field definitions
+     * Backend returns non-paginated array sorted by sortOrder
+     */
+    async getDefinitions(entityType) {
+        const params = new URLSearchParams();
+        if (entityType) {
+            params.append('entityType', entityType);
+        }
+        const query = params.toString();
+        const url = query ? `${this.basePath}?${query}` : this.basePath;
+        return this.apiClient.get(url);
+    }
+    /**
+     * Get a single custom field definition by ID
+     */
+    async getDefinition(id) {
+        return this.apiClient.get(`${this.basePath}/${id}`);
+    }
+    /**
+     * Create a new custom field definition
+     */
+    async createDefinition(data) {
+        return this.apiClient.post(this.basePath, data);
+    }
+    /**
+     * Update an existing custom field definition
+     */
+    async updateDefinition(id, data) {
+        return this.apiClient.put(`${this.basePath}/${id}`, data);
+    }
+    /**
+     * Delete a custom field definition
+     */
+    async deleteDefinition(id) {
+        return this.apiClient.delete(`${this.basePath}/${id}`);
+    }
+    /**
+     * Get usage count for a field definition
+     */
+    async getUsages(id) {
+        return this.apiClient.get(`${this.basePath}/${id}/usages`);
+    }
+    /**
+     * Resolve dynamic select options for a field
+     */
+    async resolveSelectOptions(id) {
+        return this.apiClient.get(`${this.basePath}/${id}/options`);
+    }
+}
+
+/**
+ * Custom Field Definition Manager - Manage tenant-specific custom fields
+ *
+ * Provides CRUD operations for custom field definitions that extend the built-in
+ * user profile fields. Custom fields are defined per-tenant and can be used for
+ * additional user data collection, redemption requirements, and form validation.
+ *
+ * @group Managers
+ * @category Custom Fields
+ *
+ * @example Basic Operations
+ * ```typescript
+ * // List all user custom fields
+ * const fields = await sdk.customFields.getDefinitions();
+ *
+ * // Create a new custom field
+ * const field = await sdk.customFields.createDefinition({
+ *   key: 'employee_id',
+ *   label: 'Employee ID',
+ *   fieldType: 'text',
+ *   validation: { required: true, pattern: '^E[0-9]{5}$' }
+ * });
+ *
+ * // Update a field
+ * await sdk.customFields.updateDefinition(field.id, {
+ *   label: 'Company Employee ID'
+ * });
+ *
+ * // Delete a field
+ * await sdk.customFields.deleteDefinition(field.id);
+ * ```
+ *
+ * @example Validation
+ * ```typescript
+ * // Validate user custom data against definitions
+ * const definitions = await sdk.customFields.getDefinitions();
+ * const errors = sdk.customFields.validateUserData(
+ *   { employee_id: 'INVALID' },
+ *   definitions
+ * );
+ * if (errors.length > 0) {
+ *   console.log('Validation errors:', errors);
+ * }
+ * ```
+ */
+class CustomFieldDefinitionManager {
+    constructor(apiClient, events) {
+        this.events = events;
+        this.api = new CustomFieldApi(apiClient);
+    }
+    /**
+     * List all custom field definitions for the tenant
+     *
+     * Retrieves all custom field definitions, optionally filtered by entity type.
+     * Results are sorted by sortOrder (ascending).
+     *
+     * @param options - Query options including entity type filter
+     * @returns Array of custom field definitions
+     *
+     * @example List All User Fields
+     * ```typescript
+     * const fields = await sdk.customFields.getDefinitions();
+     * console.log(`Found ${fields.length} custom fields`);
+     *
+     * fields.forEach(field => {
+     *   console.log(`${field.key}: ${field.label} (${field.fieldType})`);
+     * });
+     * ```
+     *
+     * @example Filter by Entity Type
+     * ```typescript
+     * // Get only business custom fields
+     * const businessFields = await sdk.customFields.getDefinitions({
+     *   entityType: 'business'
+     * });
+     * ```
+     */
+    async getDefinitions(options) {
+        return this.api.getDefinitions(options?.entityType);
+    }
+    /**
+     * Get a single custom field definition by ID
+     *
+     * @param id - The UUID of the custom field definition
+     * @returns The custom field definition
+     * @throws {PersApiError} When definition not found (404)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const field = await sdk.customFields.getDefinition('uuid-here');
+     *   console.log('Field:', field.label);
+     * } catch (error) {
+     *   if (error.statusCode === 404) {
+     *     console.log('Field not found');
+     *   }
+     * }
+     * ```
+     */
+    async getDefinition(id) {
+        return this.api.getDefinition(id);
+    }
+    /**
+     * Create a new custom field definition
+     *
+     * Creates a new custom field for the tenant. The field key must be unique
+     * within the tenant and entity type combination.
+     *
+     * @param data - The field definition data
+     * @returns The created custom field definition
+     * @throws {PersApiError} When key already exists (409) or validation fails (400)
+     *
+     * @example Text Field with Pattern
+     * ```typescript
+     * const employeeIdField = await sdk.customFields.createDefinition({
+     *   key: 'employee_id',
+     *   label: 'Employee ID',
+     *   description: 'Your company employee ID (E + 5 digits)',
+     *   fieldType: 'text',
+     *   validation: {
+     *     required: true,
+     *     pattern: '^E[0-9]{5}$',
+     *     patternMessage: 'Must be E followed by 5 digits'
+     *   },
+     *   sortOrder: 1
+     * });
+     * ```
+     *
+     * @example Date Field with Comparison
+     * ```typescript
+     * const checkOutField = await sdk.customFields.createDefinition({
+     *   key: 'check_out',
+     *   label: 'Check-out Date',
+     *   fieldType: 'date',
+     *   validation: {
+     *     required: true,
+     *     comparisons: [
+     *       { field: 'check_in', operator: '>', message: 'Must be after check-in' }
+     *     ]
+     *   },
+     *   sortOrder: 2
+     * });
+     * ```
+     *
+     * @example Select Field with Static Options
+     * ```typescript
+     * const departmentField = await sdk.customFields.createDefinition({
+     *   key: 'department',
+     *   label: 'Department',
+     *   fieldType: 'select',
+     *   selectOptions: [
+     *     { value: 'engineering', label: 'Engineering' },
+     *     { value: 'sales', label: 'Sales' },
+     *     { value: 'hr', label: 'Human Resources' }
+     *   ],
+     *   validation: { required: true }
+     * });
+     * ```
+     *
+     * @example Select Field with Dynamic Options
+     * ```typescript
+     * const hotelField = await sdk.customFields.createDefinition({
+     *   key: 'preferred_hotel',
+     *   label: 'Preferred Hotel',
+     *   fieldType: 'select',
+     *   selectOptionsSource: {
+     *     entity: 'business',
+     *     valueField: 'id',
+     *     labelField: 'name',
+     *     filter: { tags: ['hotel'], isActive: true }
+     *   },
+     *   validation: { required: true }
+     * });
+     * ```
+     */
+    async createDefinition(data) {
+        const result = await this.api.createDefinition(data);
+        // Using 'user' domain until pers-shared adds 'customField' domain
+        this.events?.emitSuccess({
+            domain: 'user',
+            type: 'definition_created',
+            userMessage: `Custom field "${result.label}" created`,
+            details: { id: result.id, key: result.key }
+        });
+        return result;
+    }
+    /**
+     * Update an existing custom field definition
+     *
+     * Updates a custom field definition. Note that key and entityType cannot
+     * be changed after creation.
+     *
+     * @param id - The UUID of the custom field definition to update
+     * @param data - The fields to update (partial update supported)
+     * @returns The updated custom field definition
+     * @throws {PersApiError} When definition not found (404) or validation fails (400)
+     *
+     * @example Update Label and Validation
+     * ```typescript
+     * const updated = await sdk.customFields.updateDefinition('uuid-here', {
+     *   label: 'Employee ID (Required)',
+     *   validation: {
+     *     required: true,
+     *     minLength: 6,
+     *     maxLength: 6
+     *   }
+     * });
+     * ```
+     *
+     * @example Update Sort Order
+     * ```typescript
+     * await sdk.customFields.updateDefinition('uuid-here', {
+     *   sortOrder: 5
+     * });
+     * ```
+     */
+    async updateDefinition(id, data) {
+        const result = await this.api.updateDefinition(id, data);
+        // Using 'user' domain until pers-shared adds 'customField' domain
+        this.events?.emitSuccess({
+            domain: 'user',
+            type: 'definition_updated',
+            userMessage: `Custom field "${result.label}" updated`,
+            details: { id: result.id, key: result.key }
+        });
+        return result;
+    }
+    /**
+     * Delete a custom field definition (soft delete)
+     *
+     * Soft deletes a custom field definition. Existing user data in customData
+     * is preserved, but the field will no longer appear in forms or validation.
+     *
+     * ⚠️ Consider the impact on existing user data before deleting.
+     *
+     * @param id - The UUID of the custom field definition to delete
+     * @throws {PersApiError} When definition not found (404)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await sdk.customFields.deleteDefinition('uuid-here');
+     *   console.log('Field deleted');
+     * } catch (error) {
+     *   console.log('Failed to delete:', error.message);
+     * }
+     * ```
+     */
+    async deleteDefinition(id) {
+        await this.api.deleteDefinition(id);
+        // Using 'user' domain until pers-shared adds 'customField' domain
+        this.events?.emitSuccess({
+            domain: 'user',
+            type: 'definition_deleted',
+            userMessage: 'Custom field deleted',
+            details: { id }
+        });
+    }
+    /**
+     * Resolve dynamic select options for a field
+     *
+     * For fields with selectOptionsSource (dynamic options from entities),
+     * this resolves the actual options by querying the source entity.
+     *
+     * @param id - The UUID of the custom field definition
+     * @returns Array of select options
+     *
+     * @example
+     * ```typescript
+     * const field = await sdk.customFields.getDefinition('hotel-field-id');
+     *
+     * if (field.selectOptionsSource) {
+     *   // Options come from entity - need to resolve
+     *   const options = await sdk.customFields.resolveSelectOptions(field.id);
+     *   console.log('Available hotels:', options);
+     * } else {
+     *   // Static options
+     *   console.log('Options:', field.selectOptions);
+     * }
+     * ```
+     */
+    async resolveSelectOptions(id) {
+        const response = await this.api.resolveSelectOptions(id);
+        return response.options;
+    }
+    /**
+     * Validate user custom data against field definitions
+     *
+     * Client-side validation using the same rules as the backend. Use this
+     * to validate form data before submission.
+     *
+     * @param data - User's custom data (key-value pairs)
+     * @param definitions - Custom field definitions to validate against
+     * @returns Array of validation errors (empty if valid)
+     *
+     * @example Form Validation
+     * ```typescript
+     * const definitions = await sdk.customFields.getDefinitions();
+     * const formData = {
+     *   employee_id: 'E123', // Missing a digit
+     *   department: 'engineering'
+     * };
+     *
+     * const errors = sdk.customFields.validateUserData(formData, definitions);
+     * if (errors.length > 0) {
+     *   errors.forEach(err => {
+     *     console.log(`${err.field}: ${err.message}`);
+     *   });
+     *   return; // Don't submit
+     * }
+     *
+     * // No errors, safe to submit
+     * await sdk.users.updateCurrentUser({ customData: formData });
+     * ```
+     */
+    validateUserData(data, definitions) {
+        // Convert CustomFieldDefinitionDTO to FieldDefinition for validation
+        const fieldDefinitions = definitions.map(def => ({
+            key: def.key,
+            fieldType: def.fieldType,
+            label: def.label,
+            validation: def.validation ?? undefined,
+        }));
+        return validateAllFields(data, fieldDefinitions);
+    }
+    /**
+     * Validate a single field value
+     *
+     * Validates a single value against a field's rules. Useful for
+     * real-time validation as the user types.
+     *
+     * @param value - The value to validate
+     * @param definition - The field definition
+     * @returns Validation error or null if valid
+     *
+     * @example Real-time Validation
+     * ```typescript
+     * const employeeIdField = definitions.find(d => d.key === 'employee_id');
+     *
+     * const handleBlur = (value: string) => {
+     *   const error = sdk.customFields.validateFieldValue(value, employeeIdField);
+     *   if (error) {
+     *     setFieldError('employee_id', error.message);
+     *   } else {
+     *     clearFieldError('employee_id');
+     *   }
+     * };
+     * ```
+     */
+    validateFieldValue(value, definition) {
+        const error = validateFieldValue(value, definition.validation ?? null, definition.fieldType);
+        if (error) {
+            // Add field key to error
+            return { ...error, field: definition.key };
+        }
+        return null;
+    }
+}
+
 /**
  * @fileoverview PERS SDK - Platform-agnostic TypeScript SDK with High-Level Managers
  *
@@ -10794,6 +11217,37 @@ class PersSDK {
         }
         return this._webhooks;
     }
+    /**
+     * Custom Field Definition Manager - Manage tenant-specific custom fields
+     *
+     * Provides CRUD operations for custom field definitions that extend the built-in
+     * user profile fields. Custom fields are tenant-specific and support validation.
+     *
+     * @returns CustomFieldDefinitionManager instance
+     *
+     * @example Basic Operations
+     * ```typescript
+     * // List all custom fields
+     * const fields = await sdk.customFields.getDefinitions();
+     *
+     * // Create a new field
+     * const field = await sdk.customFields.createDefinition({
+     *   key: 'employee_id',
+     *   label: 'Employee ID',
+     *   fieldType: 'text',
+     *   validation: { required: true }
+     * });
+     *
+     * // Validate user data
+     * const errors = sdk.customFields.validateUserData(formData, fields.data);
+     * ```
+     */
+    get customFields() {
+        if (!this._customFields) {
+            this._customFields = new CustomFieldDefinitionManager(this.apiClient, this._events);
+        }
+        return this._customFields;
+    }
     /**
      * Wallet Events Manager - Real-time blockchain events for user's wallets
      *
@@ -10900,5 +11354,5 @@ function createPersSDK(httpClient, config) {
     return new PersSDK(httpClient, config);
 }
 
-export { AuthTokenManager as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, WalletEventsManager as E, FATAL_AUTH_CODES as F, AuthStatus as G, FileApi as H, IndexedDBTokenStorage as I, FileService as J, ApiKeyApi as K, LocalStorageTokenStorage as L, MemoryTokenStorage as M, WebhookApi as N, WebhookService as O, PersSDK as P, PersEventsClient as Q, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, createPersEventsClient as V, WebDPoPCryptoProvider as W, AUTH_STORAGE_KEYS as a, DPOP_STORAGE_KEYS as b, SDK_VERSION as c, SDK_USER_AGENT as d, createPersSDK as e, PersApiClient as f, DEFAULT_PERS_CONFIG as g, buildApiRoot as h, buildWalletEventsWsUrl as i, StaticJwtAuthProvider as j, AuthApi as k, isFatalAuthErrorInMessage as l, mergeWithDefaults as m, AuthService as n, DPoPManager as o, PersEventEmitter as p, AuthManager as q, UserStatusManager as r, TransactionManager as s, PurchaseManager as t, FileManager as u, ApiKeyManager as v, AnalyticsManager as w, DonationManager as x, TriggerSourceManager as y, WebhookManager as z };
-//# sourceMappingURL=pers-sdk-DxYmXQcW.js.map
+export { AuthTokenManager as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, WalletEventsManager as E, FATAL_AUTH_CODES as F, CustomFieldDefinitionManager as G, AuthStatus as H, IndexedDBTokenStorage as I, FileApi as J, FileService as K, LocalStorageTokenStorage as L, MemoryTokenStorage as M, ApiKeyApi as N, WebhookApi as O, PersSDK as P, WebhookService as Q, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, PersEventsClient as V, WebDPoPCryptoProvider as W, createPersEventsClient as X, AUTH_STORAGE_KEYS as a, DPOP_STORAGE_KEYS as b, SDK_VERSION as c, SDK_USER_AGENT as d, createPersSDK as e, PersApiClient as f, DEFAULT_PERS_CONFIG as g, buildApiRoot as h, buildWalletEventsWsUrl as i, StaticJwtAuthProvider as j, AuthApi as k, isFatalAuthErrorInMessage as l, mergeWithDefaults as m, AuthService as n, DPoPManager as o, PersEventEmitter as p, AuthManager as q, UserStatusManager as r, TransactionManager as s, PurchaseManager as t, FileManager as u, ApiKeyManager as v, AnalyticsManager as w, DonationManager as x, TriggerSourceManager as y, WebhookManager as z };
+//# sourceMappingURL=pers-sdk-CBRtrG03.js.map