@opencrvs/toolkit 2.0.0-rc.fef9d21 → 2.0.0-rc.ff1424b

package/dist/commons/application-config/index.d.ts

@@ -24,8 +24,14 @@ export declare const ApplicationConfig: z.ZodObject<{
         label: z.ZodObject<import("./events/TranslationConfig").MessageDescriptorZod, z.core.$strip>;
     }, z.core.$strip>>;
     PHONE_NUMBER_PATTERN: z.ZodUnion<[z.ZodString, z.ZodCustom<RegExp, RegExp>]>;
-    USER_NOTIFICATION_DELIVERY_METHOD: z.ZodString;
-    INFORMANT_NOTIFICATION_DELIVERY_METHOD: z.ZodString;
+    USER_NOTIFICATION_DELIVERY_METHOD: z.ZodEnum<{
+        email: "email";
+        sms: "sms";
+    }>;
+    INFORMANT_NOTIFICATION_DELIVERY_METHOD: z.ZodEnum<{
+        email: "email";
+        sms: "sms";
+    }>;
     SEARCH_DEFAULT_CRITERIA: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         NAME: "NAME";
         EMAIL: "EMAIL";
@@ -46,8 +52,14 @@ export declare const BackgroundConfig: z.ZodObject<{
 export declare const LoginConfig: z.ZodObject<{
     COUNTRY: z.ZodString;
     LANGUAGES: z.ZodArray<z.ZodString>;
-    USER_NOTIFICATION_DELIVERY_METHOD: z.ZodString;
-    INFORMANT_NOTIFICATION_DELIVERY_METHOD: z.ZodString;
+    USER_NOTIFICATION_DELIVERY_METHOD: z.ZodEnum<{
+        email: "email";
+        sms: "sms";
+    }>;
+    INFORMANT_NOTIFICATION_DELIVERY_METHOD: z.ZodEnum<{
+        email: "email";
+        sms: "sms";
+    }>;
     PHONE_NUMBER_PATTERN: z.ZodUnion<[z.ZodString, z.ZodCustom<RegExp, RegExp>]>;
     LOGIN_BACKGROUND: z.ZodObject<{
         backgroundColor: z.ZodOptional<z.ZodString>;
@@ -62,6 +74,7 @@ export declare const ClientConfig: z.ZodObject<{
     COUNTRY: z.ZodString;
     LANGUAGES: z.ZodArray<z.ZodString>;
     SENTRY: z.ZodOptional<z.ZodString>;
+    LOGIN_URL: z.ZodOptional<z.ZodString>;
     REGISTER_BACKGROUND: z.ZodObject<{
         backgroundColor: z.ZodOptional<z.ZodString>;
         backgroundImage: z.ZodOptional<z.ZodString>;

package/dist/commons/conditionals/conditionals.d.ts

@@ -1,12 +1,13 @@
 import { EventDocument } from '../events/EventDocument';
-import { EventState } from '../events/ActionDocument';
+import { ActionUpdate, EventState } from '../events/ActionDocument';
 import { ITokenPayload as TokenPayload } from '../authentication';
 import { PartialSchema as AjvJSONSchemaType } from 'ajv/dist/types/json-schema';
 import { userSerializer } from '../events/serializers/user/serializer';
 import { UUID } from '../uuid';
 import { todayDateTimeValueSerializer } from '../events/serializers/date/serializer';
 import { EventStatus } from '../events/EventMetadata';
-import { FieldReference } from '../events/FieldConfig';
+import { CodeToEvaluate, FieldReference } from '../events/FieldConfig';
+import type { ClientFunctionContext } from './validate';
 /** @knipignore */
 export type JSONSchema = {
     $id: string;
@@ -25,7 +26,7 @@ export type EventConditionalParameters = CommonConditionalParameters & {
     $event: EventDocument;
 };
 export type FormConditionalParameters = CommonConditionalParameters & {
-    $form: EventState | Record<string, unknown>;
+    $form: EventState | ActionUpdate;
     $leafAdminStructureLocationIds?: Array<{
         id: UUID;
     }>;
@@ -67,6 +68,12 @@ export declare function not(condition: AjvJSONSchema): JSONSchema;
  * @returns {JSONSchema} An schema object that always evaluates to false.
  */
 export declare function never(): JSONSchema;
+/**
+ * Returns an JSON Schema object, which is treated as always valid.
+ *
+ * @returns {JSONSchema} An schema object that always evaluates to true.
+ */
+export declare function always(): JSONSchema;
 /**
  * Generate conditional rules for current date
  */
@@ -86,22 +93,24 @@ export declare const user: typeof userSerializer & {
     };
     scope: (scope: import("../scopes").ScopeType) => {
         attribute: (option: import("../scopes").ScopeOptionKey) => {
-            $scope: "record.search" | "record.create" | "record.read" | "record.declare" | "record.notify" | "record.edit" | "record.reject" | "record.archive" | "record.review-duplicates" | "record.register" | "record.print-certified-copies" | "record.request-correction" | "record.correct" | "record.unassign-others" | "record.custom-action" | "bypassratelimit" | "record.reindex" | "user.data-seeding" | "integration.create" | "record.import" | "config.update-all" | "attachment.upload" | "profile.electronic-signature" | "user.read-only-my-audit" | "performance.read" | "performance.read-dashboards" | "performance.vital-statistics-export" | "record.confirm-registration" | "record.reject-registration" | "organisation.read-locations" | "user.read" | "user.create" | "user.edit" | "workqueue" | "dashboard.view";
-            $option: "event" | "placeOfEvent" | "declaredIn" | "declaredBy" | "registeredIn" | "registeredBy" | "accessLevel" | "ids";
+            $scope: "record.search" | "record.create" | "record.read" | "record.declare" | "record.notify" | "record.edit" | "record.reject" | "record.archive" | "record.review-duplicates" | "record.register" | "record.print-certified-copies" | "record.request-correction" | "record.correct" | "record.unassign-others" | "record.custom-action" | "bypassratelimit" | "record.reindex" | "user.data-seeding" | "integration.create" | "record.import" | "config.update-all" | "attachment.upload" | "profile.electronic-signature" | "user.read-only-my-audit" | "performance.read" | "performance.read-dashboards" | "performance.vital-statistics-export" | "record.confirm-registration" | "record.reject-registration" | "organisation.read-locations" | "user.read" | "user.create" | "user.edit" | "user.search" | "workqueue" | "dashboard.view";
+            $option: "role" | "event" | "placeOfEvent" | "declaredIn" | "declaredBy" | "registeredIn" | "registeredBy" | "accessLevel" | "ids";
         };
     };
     jurisdiction: (jurisdiction: import("../scopes").JurisdictionFilter | {
-        $scope: "record.search" | "record.create" | "record.read" | "record.declare" | "record.notify" | "record.edit" | "record.reject" | "record.archive" | "record.review-duplicates" | "record.register" | "record.print-certified-copies" | "record.request-correction" | "record.correct" | "record.unassign-others" | "record.custom-action" | "bypassratelimit" | "record.reindex" | "user.data-seeding" | "integration.create" | "record.import" | "config.update-all" | "attachment.upload" | "profile.electronic-signature" | "user.read-only-my-audit" | "performance.read" | "performance.read-dashboards" | "performance.vital-statistics-export" | "record.confirm-registration" | "record.reject-registration" | "organisation.read-locations" | "user.read" | "user.create" | "user.edit" | "workqueue" | "dashboard.view";
-        $option: "event" | "placeOfEvent" | "declaredIn" | "declaredBy" | "registeredIn" | "registeredBy" | "accessLevel" | "ids";
+        $scope: "record.search" | "record.create" | "record.read" | "record.declare" | "record.notify" | "record.edit" | "record.reject" | "record.archive" | "record.review-duplicates" | "record.register" | "record.print-certified-copies" | "record.request-correction" | "record.correct" | "record.unassign-others" | "record.custom-action" | "bypassratelimit" | "record.reindex" | "user.data-seeding" | "integration.create" | "record.import" | "config.update-all" | "attachment.upload" | "profile.electronic-signature" | "user.read-only-my-audit" | "performance.read" | "performance.read-dashboards" | "performance.vital-statistics-export" | "record.confirm-registration" | "record.reject-registration" | "organisation.read-locations" | "user.read" | "user.create" | "user.edit" | "user.search" | "workqueue" | "dashboard.view";
+        $option: "role" | "event" | "placeOfEvent" | "declaredIn" | "declaredBy" | "registeredIn" | "registeredBy" | "accessLevel" | "ids";
     }) => {
         $jurisdiction: "administrativeArea" | "location" | "all" | {
-            $scope: "record.search" | "record.create" | "record.read" | "record.declare" | "record.notify" | "record.edit" | "record.reject" | "record.archive" | "record.review-duplicates" | "record.register" | "record.print-certified-copies" | "record.request-correction" | "record.correct" | "record.unassign-others" | "record.custom-action" | "bypassratelimit" | "record.reindex" | "user.data-seeding" | "integration.create" | "record.import" | "config.update-all" | "attachment.upload" | "profile.electronic-signature" | "user.read-only-my-audit" | "performance.read" | "performance.read-dashboards" | "performance.vital-statistics-export" | "record.confirm-registration" | "record.reject-registration" | "organisation.read-locations" | "user.read" | "user.create" | "user.edit" | "workqueue" | "dashboard.view";
-            $option: "event" | "placeOfEvent" | "declaredIn" | "declaredBy" | "registeredIn" | "registeredBy" | "accessLevel" | "ids";
+            $scope: "record.search" | "record.create" | "record.read" | "record.declare" | "record.notify" | "record.edit" | "record.reject" | "record.archive" | "record.review-duplicates" | "record.register" | "record.print-certified-copies" | "record.request-correction" | "record.correct" | "record.unassign-others" | "record.custom-action" | "bypassratelimit" | "record.reindex" | "user.data-seeding" | "integration.create" | "record.import" | "config.update-all" | "attachment.upload" | "profile.electronic-signature" | "user.read-only-my-audit" | "performance.read" | "performance.read-dashboards" | "performance.vital-statistics-export" | "record.confirm-registration" | "record.reject-registration" | "organisation.read-locations" | "user.read" | "user.create" | "user.edit" | "user.search" | "workqueue" | "dashboard.view";
+            $option: "role" | "event" | "placeOfEvent" | "declaredIn" | "declaredBy" | "registeredIn" | "registeredBy" | "accessLevel" | "ids";
         };
     };
 };
 export declare function isFieldReference(value: unknown): value is FieldReference;
-export declare function isEventFieldReference(value: unknown): value is FieldReference;
+export declare function isEventFieldReference(value: unknown): value is {
+    $$event: string;
+};
 /** Check if an event flag is present */
 export declare function flag(flagvalue: string): JSONSchema;
 /** Check if an event flag is present */
@@ -196,6 +205,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         asDob(): any;
         asAge(): any;
@@ -255,6 +295,37 @@ export declare function createFieldConditionals(fieldId: string): {
          * )
          */
         object: (options: Record<string, any>) => JSONSchema;
+        /**
+         * Custom client-side validator. The provided function is serialised and executed
+         * just-in-time on the client only. External references (e.g. lodash) are not
+         * available inside the function body — all logic must be self-contained.
+         *
+         * @example
+         * field('nid').customClientValidator((value) => {
+         *   // LUHN check — all logic must be inline
+         *   const digits = String(value).split('').map(Number)
+         *   // ...
+         *   return isValid
+         * })
+         */
+        customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+        /**
+         * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+         * that can be used as the `value` property or a DATA component entry.
+         * The function receives the referenced field's value as the first argument and
+         * the full form context as the second; its return value replaces the field reference.
+         * The function is serialised and executed just-in-time on the client only.
+         * External references (e.g. lodash) are not available inside the function body.
+         *
+         * For computing a default value without referencing a specific field, use
+         * `evaluate(fn)` in the `defaultValue` property instead.
+         *
+         * @example
+         * field('a').customClientEvaluation((aValue, ctx) =>
+         *   Number(aValue) + Number(ctx.$form.b)
+         * )
+         */
+        customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
     };
     getByPath(fieldPath: string[]): {
         $$subfield: string[];
@@ -328,6 +399,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         getByPath(fieldPath: string[]): any;
         asDob(): {
@@ -396,6 +498,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         asAge(): {
             $$subfield: string[];
@@ -463,6 +596,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         isAfter(): {
             days: (days: number) => {
@@ -520,6 +684,37 @@ export declare function createFieldConditionals(fieldId: string): {
          * )
          */
         object: (options: Record<string, any>) => JSONSchema;
+        /**
+         * Custom client-side validator. The provided function is serialised and executed
+         * just-in-time on the client only. External references (e.g. lodash) are not
+         * available inside the function body — all logic must be self-contained.
+         *
+         * @example
+         * field('nid').customClientValidator((value) => {
+         *   // LUHN check — all logic must be inline
+         *   const digits = String(value).split('').map(Number)
+         *   // ...
+         *   return isValid
+         * })
+         */
+        customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+        /**
+         * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+         * that can be used as the `value` property or a DATA component entry.
+         * The function receives the referenced field's value as the first argument and
+         * the full form context as the second; its return value replaces the field reference.
+         * The function is serialised and executed just-in-time on the client only.
+         * External references (e.g. lodash) are not available inside the function body.
+         *
+         * For computing a default value without referencing a specific field, use
+         * `evaluate(fn)` in the `defaultValue` property instead.
+         *
+         * @example
+         * field('a').customClientEvaluation((aValue, ctx) =>
+         *   Number(aValue) + Number(ctx.$form.b)
+         * )
+         */
+        customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
     };
     asDob(): {
         $$subfield: string[];
@@ -594,6 +789,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         asDob(): any;
         asAge(): any;
@@ -653,6 +879,37 @@ export declare function createFieldConditionals(fieldId: string): {
          * )
          */
         object: (options: Record<string, any>) => JSONSchema;
+        /**
+         * Custom client-side validator. The provided function is serialised and executed
+         * just-in-time on the client only. External references (e.g. lodash) are not
+         * available inside the function body — all logic must be self-contained.
+         *
+         * @example
+         * field('nid').customClientValidator((value) => {
+         *   // LUHN check — all logic must be inline
+         *   const digits = String(value).split('').map(Number)
+         *   // ...
+         *   return isValid
+         * })
+         */
+        customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+        /**
+         * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+         * that can be used as the `value` property or a DATA component entry.
+         * The function receives the referenced field's value as the first argument and
+         * the full form context as the second; its return value replaces the field reference.
+         * The function is serialised and executed just-in-time on the client only.
+         * External references (e.g. lodash) are not available inside the function body.
+         *
+         * For computing a default value without referencing a specific field, use
+         * `evaluate(fn)` in the `defaultValue` property instead.
+         *
+         * @example
+         * field('a').customClientEvaluation((aValue, ctx) =>
+         *   Number(aValue) + Number(ctx.$form.b)
+         * )
+         */
+        customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
     };
     asAge(): {
         $$subfield: string[];
@@ -727,6 +984,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         asDob(): any;
         asAge(): any;
@@ -786,6 +1074,37 @@ export declare function createFieldConditionals(fieldId: string): {
          * )
          */
         object: (options: Record<string, any>) => JSONSchema;
+        /**
+         * Custom client-side validator. The provided function is serialised and executed
+         * just-in-time on the client only. External references (e.g. lodash) are not
+         * available inside the function body — all logic must be self-contained.
+         *
+         * @example
+         * field('nid').customClientValidator((value) => {
+         *   // LUHN check — all logic must be inline
+         *   const digits = String(value).split('').map(Number)
+         *   // ...
+         *   return isValid
+         * })
+         */
+        customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+        /**
+         * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+         * that can be used as the `value` property or a DATA component entry.
+         * The function receives the referenced field's value as the first argument and
+         * the full form context as the second; its return value replaces the field reference.
+         * The function is serialised and executed just-in-time on the client only.
+         * External references (e.g. lodash) are not available inside the function body.
+         *
+         * For computing a default value without referencing a specific field, use
+         * `evaluate(fn)` in the `defaultValue` property instead.
+         *
+         * @example
+         * field('a').customClientEvaluation((aValue, ctx) =>
+         *   Number(aValue) + Number(ctx.$form.b)
+         * )
+         */
+        customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
     };
     isAfter(): {
         days: (days: number) => {
@@ -843,6 +1162,37 @@ export declare function createFieldConditionals(fieldId: string): {
      * )
      */
     object: (options: Record<string, any>) => JSONSchema;
+    /**
+     * Custom client-side validator. The provided function is serialised and executed
+     * just-in-time on the client only. External references (e.g. lodash) are not
+     * available inside the function body — all logic must be self-contained.
+     *
+     * @example
+     * field('nid').customClientValidator((value) => {
+     *   // LUHN check — all logic must be inline
+     *   const digits = String(value).split('').map(Number)
+     *   // ...
+     *   return isValid
+     * })
+     */
+    customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+    /**
+     * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+     * that can be used as the `value` property or a DATA component entry.
+     * The function receives the referenced field's value as the first argument and
+     * the full form context as the second; its return value replaces the field reference.
+     * The function is serialised and executed just-in-time on the client only.
+     * External references (e.g. lodash) are not available inside the function body.
+     *
+     * For computing a default value without referencing a specific field, use
+     * `evaluate(fn)` in the `defaultValue` property instead.
+     *
+     * @example
+     * field('a').customClientEvaluation((aValue, ctx) =>
+     *   Number(aValue) + Number(ctx.$form.b)
+     * )
+     */
+    customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
 };
 export {};
 //# sourceMappingURL=conditionals.d.ts.map

package/dist/commons/conditionals/validate.d.ts

@@ -12,6 +12,54 @@ import { ActionType } from '../events/ActionType';
 import { EventConfig } from '../events/EventConfig';
 import { EventDocument } from '../events/EventDocument';
 import { EventIndex } from '../events/EventIndex';
+import { Location } from '../events/locations';
+import { SystemVariables } from '../events/TemplateConfig';
+/** Returns today's date as an ISO date string (YYYY-MM-DD). */
+export declare function todayISO(): string;
+/**
+ * Context passed to every serialised client-side function ({@link runClientFunction}).
+ *
+ * `$user` (full {@link ITokenPayload}, validator paths) and `user` (a
+ * {@link SystemVariables} subset for template substitution, default-value
+ * path) are distinct sources, not duplicates.
+ */
+export type ClientFunctionContext = {
+    $form: EventState | ActionUpdate;
+    $now: string;
+    $online: boolean;
+    $user?: ITokenPayload;
+    $event?: EventDocument;
+    $leafAdminStructureLocationIds: Array<{
+        id: UUID;
+    }>;
+    user?: SystemVariables['user'];
+    $window?: SystemVariables['$window'];
+    locations?: Location[];
+    adminLevelIds?: string[];
+    $flags?: string[];
+    $status?: string;
+};
+type CompiledClientFunction = (data: FieldValue | undefined, context: ClientFunctionContext) => unknown;
+/**
+ * Deserialises a serialised function string (produced by `.toString()`) into a callable.
+ * Results are cached by code string so each unique function body is compiled at most once.
+ * Runs in a clean scope — no access to outer closures or external imports.
+ */
+export declare function compileClientFunction(code: string): CompiledClientFunction;
+export declare function buildClientFunctionContext(input: {
+    form: EventState | ActionUpdate;
+    validatorContext?: ValidatorContext;
+    systemVariables?: SystemVariables;
+    /**
+     * In real use cases, there can be hundreds of thousands of locations.
+     * Make sure that the context contains only the locations that are needed for validation.
+     * E.g. if the user is a leaf admin, only the leaf locations under their admin structure are needed.
+     * Loading few megabytes of locations to memory just for validation is not efficient and will choke the application.
+     */
+    locations?: Location[];
+    adminLevelIds?: string[];
+}): ClientFunctionContext;
+export declare function runClientFunction(code: string, data: FieldValue | undefined, context: ClientFunctionContext): unknown;
 /**
  * Precompiles action conditional schemas from the event configurations to improve performance of condition validation later on.
  * Best called once on application startup before any condition validation is done.
@@ -20,14 +68,15 @@ export declare function precompileActionSchemas(eventConfigurations: EventConfig
 export declare function validate(schema: JSONSchema, data: ConditionalParameters): boolean;
 export declare function validateValue(schema: JSONSchema, data: unknown): boolean;
 export declare function isOnline(): boolean;
-export declare function isConditionMet(conditional: JSONSchema, values: EventState | ActionUpdate, context: ValidatorContext, eventIndex?: EventIndex): boolean;
-export declare function areConditionsMet(conditions: FieldConditional[], values: Record<string, FieldValue>, context: ValidatorContext, event: EventIndex): boolean;
+export declare function isConditionMet(conditional: JSONSchema, values: EventState | ActionUpdate, context: ValidatorContext): boolean;
+export declare function areConditionsMet(conditions: FieldConditional[], values: Record<string, FieldValue>, context: ValidatorContext, _event: EventIndex): boolean;
 export type ValidatorContext = {
     user?: ITokenPayload;
     leafAdminStructureLocationIds?: Array<{
         id: UUID;
     }>;
     event?: EventDocument;
+    baseFormState?: EventState;
 };
 export declare function isFieldVisible(field: FieldConfig, form: Partial<ActionUpdate | EventState>, context: ValidatorContext): boolean;
 export declare function isFieldEnabled(field: FieldConfig, form: ActionUpdate | EventState, context: ValidatorContext): boolean;
@@ -112,4 +161,5 @@ export declare function runFieldValidations({ field: config, form, value, contex
 }>>;
 export declare function getValidatorsForField(fieldId: FieldConfig['id'], validations: NonNullable<FieldConfig['validation']>): NonNullable<FieldConfig['validation']>;
 export declare function areCertificateConditionsMet(conditions: FieldConditional[], values: ConditionalParameters): boolean;
+export {};
 //# sourceMappingURL=validate.d.ts.map

package/dist/commons/events/ActionConfig.d.ts

@@ -85,6 +85,32 @@ export declare const ActionConfig: z.ZodDiscriminatedUnion<[z.ZodObject<{
         fields: z.ZodArray<z.ZodType<FieldConfig, import("./FieldConfig").FieldConfigInput, z.core.$ZodTypeInternals<FieldConfig, import("./FieldConfig").FieldConfigInput>>>;
     }, z.core.$strip>;
     conditionals: z.ZodOptional<z.ZodNever>;
+}, z.core.$strip>, z.ZodObject<{
+    label: z.ZodObject<import("./TranslationConfig").MessageDescriptorZod, z.core.$strip>;
+    flags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodEnum<{
+            readonly INCOMPLETE: "incomplete";
+            readonly REJECTED: "rejected";
+            readonly CORRECTION_REQUESTED: "correction-requested";
+            readonly POTENTIAL_DUPLICATE: "potential-duplicate";
+            readonly EDIT_IN_PROGRESS: "edit-in-progress";
+        }>]>, z.ZodString]>;
+        operation: z.ZodEnum<{
+            add: "add";
+            remove: "remove";
+        }>;
+        conditional: z.ZodOptional<z.ZodAny>;
+    }, z.core.$strip>>>>;
+    supportingCopy: z.ZodOptional<z.ZodObject<import("./TranslationConfig").MessageDescriptorZod, z.core.$strip>>;
+    icon: z.ZodOptional<z.ZodString>;
+    conditionals: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"SHOW">;
+        conditional: z.ZodAny;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"ENABLE">;
+        conditional: z.ZodAny;
+    }, z.core.$strip>], "type">>>;
+    type: z.ZodLiteral<"NOTIFY">;
 }, z.core.$strip>, z.ZodObject<{
     label: z.ZodObject<import("./TranslationConfig").MessageDescriptorZod, z.core.$strip>;
     flags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -388,8 +414,8 @@ export declare const actionConfigTypes: Set<ActionConfigTypes>;
  *
  * These are not the same as the broader workflow `action.type` values.
  * `ActionConfigTypes` includes only the action kinds that can be defined
- * in the country configuration (e.g. DECLARE, VALIDATE, CUSTOM), and
- * excludes workflow-only types such as CREATE or NOTIFY.
+ * in the country configuration (e.g. NOTIFY, DECLARE, VALIDATE, CUSTOM), and
+ * excludes workflow-only types such as CREATE.
  */
 export type ActionConfigTypes = ActionConfig['type'];
 export declare const DeclarationActionConfig: z.ZodDiscriminatedUnion<[z.ZodObject<{