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

package/dist/chunks/{pers-sdk-DeFxjuRB.cjs → pers-sdk-DcNDMx1Y.cjs}

@@ -1587,7 +1587,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}`;
 
@@ -10108,6 +10108,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 persShared.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 = persShared.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
  *
@@ -10796,6 +11219,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
      *
@@ -10912,6 +11366,7 @@ exports.AuthService = AuthService;
 exports.AuthTokenManager = AuthTokenManager;
 exports.BusinessManager = BusinessManager;
 exports.CampaignManager = CampaignManager;
+exports.CustomFieldDefinitionManager = CustomFieldDefinitionManager;
 exports.DEFAULT_PERS_CONFIG = DEFAULT_PERS_CONFIG;
 exports.DPOP_STORAGE_KEYS = DPOP_STORAGE_KEYS;
 exports.DPoPManager = DPoPManager;
@@ -10950,4 +11405,4 @@ exports.createPersEventsClient = createPersEventsClient;
 exports.createPersSDK = createPersSDK;
 exports.isFatalAuthErrorInMessage = isFatalAuthErrorInMessage;
 exports.mergeWithDefaults = mergeWithDefaults;
-//# sourceMappingURL=pers-sdk-DeFxjuRB.cjs.map
+//# sourceMappingURL=pers-sdk-DcNDMx1Y.cjs.map