@webitel/api-services 0.1.69 → 0.1.70

package/src/validations/queue/__tests__/queue.validations.spec.ts

@@ -0,0 +1,159 @@
+import { get, set } from 'lodash-es';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import {
+	getQueueDefaults,
+	QueueTypeDefaults,
+} from '../../../api/clients/queues/defaults/queueTypeDefaults';
+import { QueueType } from '../../../enums';
+import { queueTypeRules, sharedQueueRules } from '../queue.rules';
+import { queueSchema, queueSchemaBase } from '../queue.validations';
+
+type AnyRecord = Record<string, unknown>;
+
+const allQueueTypes = Object.values(QueueType);
+
+/** Lookup fields are `{ id, name }`; everything else required here is scalar. */
+const lookupPaths = new Set([
+	'calendar',
+	'schema',
+	'team',
+	'dncList',
+	'grantee',
+	'ringtone',
+	'doSchema',
+	'afterSchema',
+	'formSchema',
+]);
+
+const filledValueFor = (path: string, current: unknown) => {
+	if (lookupPaths.has(path))
+		return {
+			id: '1',
+			name: 'x',
+		};
+	if (typeof current === 'number') return Math.max(current, 1);
+	if (typeof current === 'string' && current) return current;
+	return 'x';
+};
+
+const requiredPathsFor = (type: number) => [
+	...(sharedQueueRules.required ?? []),
+	...(queueTypeRules[type]?.required ?? []),
+];
+
+/** A queue of `type` with every required field filled in. */
+const validQueueFor = (type: number): AnyRecord => {
+	const queue = getQueueDefaults(type) as AnyRecord;
+	queue.name = 'Support';
+	for (const path of requiredPathsFor(type)) {
+		set(queue, path, filledValueFor(path, get(queue, path)));
+	}
+	return queue;
+};
+
+const issuePaths = (result: z.ZodSafeParseResult<unknown>) =>
+	result.success
+		? []
+		: result.error.issues.map((issue) => issue.path.join('.'));
+
+describe('queueSchema', () => {
+	/**
+	 * `createCardStore` takes the schema straight, and
+	 * `getShallowFieldsToSendFromZodSchema` calls `.keyof()` on it. Since zod 4
+	 * keeps refinements inside the schema, `.superRefine` must leave a
+	 * `ZodObject` behind — if that ever regresses, both break at once.
+	 */
+	it('stays a ZodObject after superRefine', () => {
+		expect(queueSchema).toBeInstanceOf(z.ZodObject);
+		expect(queueSchema.keyof().options).toEqual(
+			queueSchemaBase.keyof().options,
+		);
+		expect(queueSchema.keyof().options).toContain('payload');
+	});
+
+	it('has a rule entry for every queue type', () => {
+		for (const type of allQueueTypes) {
+			expect(queueTypeRules[type], `missing rules for ${type}`).toBeDefined();
+		}
+	});
+
+	it.each(allQueueTypes)('accepts a fully filled queue of type %i', (type) => {
+		const result = queueSchema.safeParse(validQueueFor(type));
+
+		expect(issuePaths(result)).toEqual([]);
+	});
+
+	/**
+	 * The behaviour that actually matters: each type's own required list is
+	 * enforced, and only for that type.
+	 */
+	it.each(allQueueTypes)('enforces every required field of type %i', (type) => {
+		for (const path of requiredPathsFor(type)) {
+			const queue = validQueueFor(type);
+			set(queue, path, lookupPaths.has(path) ? {} : '');
+
+			expect(
+				issuePaths(queueSchema.safeParse(queue)),
+				`${path} should be required for type ${type}`,
+			).toContain(path);
+		}
+	});
+
+	it.each(allQueueTypes)('enforces the minimums of type %i', (type) => {
+		const minimums = {
+			...sharedQueueRules.minValue,
+			...queueTypeRules[type]?.minValue,
+		};
+
+		for (const [path, min] of Object.entries(minimums)) {
+			const queue = validQueueFor(type);
+			set(queue, path, min - 1);
+
+			expect(
+				issuePaths(queueSchema.safeParse(queue)),
+				`${path} should be >= ${min} for type ${type}`,
+			).toContain(path);
+		}
+	});
+
+	/** Vuelidate's `required` treats 0 and false as filled; ours must too. */
+	it('treats a zero priority as filled rather than missing', () => {
+		const queue = validQueueFor(QueueType.INBOUND_QUEUE);
+		queue.priority = 0;
+
+		expect(issuePaths(queueSchema.safeParse(queue))).not.toContain('priority');
+	});
+
+	it('does not require team, which the legacy rules never enforced', () => {
+		const queue = validQueueFor(QueueType.OFFLINE_QUEUE);
+		queue.team = {};
+
+		expect(issuePaths(queueSchema.safeParse(queue))).not.toContain('team');
+	});
+
+	/**
+	 * Regle builds `$fields` from state keys, so anything the defaults seed must
+	 * survive the schema — a key the schema strips has no validation entry, and
+	 * the field silently loses its required marker and error text.
+	 */
+	it.each(allQueueTypes)('keeps every seeded key of type %i', (type) => {
+		const defaults = QueueTypeDefaults[type]() as AnyRecord;
+		const parsed = queueSchemaBase.parse(validQueueFor(type)) as AnyRecord;
+
+		for (const key of Object.keys(defaults)) {
+			expect(
+				parsed,
+				`top-level ${key} stripped for type ${type}`,
+			).toHaveProperty(key);
+		}
+
+		for (const key of Object.keys(defaults.payload as AnyRecord)) {
+			expect(
+				parsed.payload,
+				`payload.${key} stripped for type ${type}`,
+			).toHaveProperty(key);
+		}
+	});
+});

package/src/validations/queue/queue.rules.ts

@@ -0,0 +1,166 @@
+import { QueueType } from '../../enums';
+
+export interface QueueTypeRule {
+	/** dot-paths, relative to the queue object */
+	required?: string[];
+	/** dot-path → inclusive minimum */
+	minValue?: Record<string, number>;
+}
+
+/**
+ * @description
+ * Per-queue-type validation, transcribed from the admin app's
+ * `opened-queue.vue` `validations()` switch.
+ *
+ * Two things in here look like mistakes and are not:
+ *
+ * - `team` is commented "required" in every legacy queue schema but was never
+ *   actually validated. That is preserved — adding it would start rejecting
+ *   queues that save fine today.
+ * - `priority` and `payload.minOnlineAgents` carry `minValue(0)` for *all* ten
+ *   types, including the ones whose form never shows `minOnlineAgents`.
+ */
+export const sharedQueueRules: QueueTypeRule = {
+	required: [
+		'name',
+	],
+	minValue: {
+		priority: 0,
+		'payload.minOnlineAgents': 0,
+	},
+};
+
+export const queueTypeRules: Record<number, QueueTypeRule> = {
+	[QueueType.OFFLINE_QUEUE]: {
+		required: [
+			'strategy',
+			'calendar',
+			'payload.originateTimeout',
+		],
+		minValue: {
+			'payload.originateTimeout': 0,
+		},
+	},
+	[QueueType.INBOUND_QUEUE]: {
+		required: [
+			'payload.timeBaseScore',
+			'payload.maxWaitTime',
+		],
+		minValue: {
+			'payload.maxWaitTime': 0,
+			'payload.discardAbandonedAfter': 0,
+		},
+	},
+	[QueueType.OUTBOUND_IVR_QUEUE]: {
+		required: [
+			'strategy',
+			'calendar',
+			'schema',
+			'payload.maxAttempts',
+			'payload.originateTimeout',
+			'payload.waitBetweenRetries',
+			'payload.resourceStrategy',
+		],
+		minValue: {
+			'payload.originateTimeout': 0,
+			'payload.waitBetweenRetries': 0,
+			'payload.minDuration': 0,
+		},
+	},
+	[QueueType.PREVIEW_DIALER]: {
+		required: [
+			'strategy',
+			'calendar',
+			'payload.maxAttempts',
+			'payload.originateTimeout',
+			'payload.waitBetweenRetries',
+			'payload.resourceStrategy',
+		],
+		minValue: {
+			'payload.originateTimeout': 0,
+			'payload.waitBetweenRetries': 0,
+		},
+	},
+	[QueueType.PROGRESSIVE_DIALER]: {
+		required: [
+			'strategy',
+			'calendar',
+			'payload.maxAttempts',
+			'payload.originateTimeout',
+			'payload.waitBetweenRetries',
+			'payload.resourceStrategy',
+			'payload.progressiveCount',
+		],
+		minValue: {
+			'payload.originateTimeout': 0,
+			'payload.waitBetweenRetries': 0,
+			'payload.progressiveCount': 1,
+		},
+	},
+	[QueueType.PREDICTIVE_DIALER]: {
+		required: [
+			'strategy',
+			'calendar',
+			'payload.maxAttempts',
+			'payload.originateTimeout',
+			'payload.waitBetweenRetries',
+			'payload.resourceStrategy',
+			'payload.progressiveCount',
+		],
+		minValue: {
+			'payload.originateTimeout': 0,
+			'payload.waitBetweenRetries': 0,
+			'payload.maxWaitTime': 0,
+			'payload.progressiveCount': 1,
+		},
+	},
+	[QueueType.CHAT_INBOUND_QUEUE]: {
+		required: [
+			'strategy',
+			'payload.timeBaseScore',
+			'payload.maxWaitTime',
+		],
+		minValue: {
+			'payload.maxWaitTime': 0,
+			'payload.discardAbandonedAfter': 0,
+		},
+	},
+	/** shares a `case` label with CHAT_INBOUND_QUEUE in the legacy switch */
+	[QueueType.IM_CHAT_QUEUE]: {
+		required: [
+			'strategy',
+			'payload.timeBaseScore',
+			'payload.maxWaitTime',
+		],
+		minValue: {
+			'payload.maxWaitTime': 0,
+			'payload.discardAbandonedAfter': 0,
+		},
+	},
+	[QueueType.INBOUND_JOB_QUEUE]: {
+		required: [
+			'strategy',
+			'calendar',
+			'payload.maxAttempts',
+			'payload.waitBetweenRetries',
+		],
+		minValue: {
+			'payload.waitBetweenRetries': 0,
+		},
+	},
+	[QueueType.OUTBOUND_JOB_QUEUE]: {
+		required: [
+			'strategy',
+			'calendar',
+			'schema',
+			'payload.maxAttempts',
+			'payload.originateTimeout',
+			'payload.waitBetweenRetries',
+		],
+		minValue: {
+			'payload.originateTimeout': 0,
+			'payload.waitBetweenRetries': 0,
+			'payload.minDuration': 0,
+		},
+	},
+};

package/src/validations/queue/queue.validations.ts

@@ -0,0 +1,105 @@
+import { get } from 'lodash-es';
+import { z } from 'zod';
+
+import { i18nIssue } from '../_shared/i18nIssue';
+import { isFilled } from '../_shared/isFilled';
+import { flexibleLookupSchema } from '../_shared/lookup.validations';
+import { variablePairSchema } from '../_shared/variablePair.validations';
+import { queueTypeRules, sharedQueueRules } from './queue.rules';
+import { queuePayloadSchema } from './queuePayload.validations';
+import { taskProcessingSchema } from './taskProcessing.validations';
+
+/**
+ * @description
+ * One flat schema covering all ten queue types, rather than a discriminated
+ * union on `type`.
+ *
+ * The union would be more precise, but Regle would then infer
+ * `validationFields` as a union too, and every form tab would need narrowing
+ * before it could read a field. Flat keeps `validationFields.<field>` reachable
+ * from every tab regardless of type, and the per-type rules move into the
+ * `superRefine` below.
+ *
+ * `.superRefine` is safe to build on here: since zod 4 it lives inside the
+ * schema and returns a `ZodObject`, so `schema.keyof()` still works and
+ * `createCardStore` still accepts it.
+ */
+export const queueSchemaBase = z.object({
+	// identity
+	name: z.string().min(1),
+	description: z.string().optional(),
+	type: z.number(),
+	enabled: z.boolean().optional(),
+	priority: z.number().optional(),
+	tags: z
+		.array(
+			z.object({
+				name: z.string(),
+			}),
+		)
+		.optional(),
+
+	// lookups
+	calendar: flexibleLookupSchema.optional(),
+	team: flexibleLookupSchema.optional(),
+	dncList: flexibleLookupSchema.optional(),
+	grantee: flexibleLookupSchema.optional(),
+	ringtone: flexibleLookupSchema.optional(),
+	schema: flexibleLookupSchema.optional(),
+	doSchema: flexibleLookupSchema.optional(),
+	afterSchema: flexibleLookupSchema.optional(),
+	formSchema: flexibleLookupSchema.optional(),
+
+	// behaviour
+	strategy: z.string().optional(),
+	stickyAgent: z.boolean().optional(),
+
+	taskProcessing: taskProcessingSchema.optional(),
+	payload: queuePayloadSchema.optional(),
+
+	variables: z.array(variablePairSchema).optional(),
+});
+
+/**
+ * Applies the rules the legacy `validations()` switch used to build per type.
+ * Paths are dotted, so an issue raised for `payload.maxWaitTime` lands on
+ * `validationFields.payload.$fields.maxWaitTime`.
+ */
+export const queueSchema = queueSchemaBase.superRefine((queue, ctx) => {
+	const rules = [
+		sharedQueueRules,
+		queueTypeRules[Number(queue.type)] ?? {},
+	];
+
+	for (const rule of rules) {
+		for (const path of rule.required ?? []) {
+			if (!isFilled(get(queue, path))) {
+				ctx.addIssue({
+					code: 'custom',
+					path: path.split('.'),
+					...i18nIssue('required'),
+				});
+			}
+		}
+
+		for (const [path, min] of Object.entries(rule.minValue ?? {})) {
+			const value = get(queue, path);
+			// an absent optional field is the `required` rules' business, not this one
+			if (value === undefined || value === null || value === '') continue;
+			if (Number(value) < min) {
+				ctx.addIssue({
+					code: 'custom',
+					path: path.split('.'),
+					message: `Value must be ${min} or greater`,
+				});
+			}
+		}
+	}
+});
+
+/**
+ * The queue as the *form* holds it. Not an entity type — it has no `id`, and
+ * `variables` is the editable pair list rather than the wire-format map. Apps
+ * pair this with `EngineQueue` for the parts the form does not own.
+ */
+export type QueueFormShape = z.infer<typeof queueSchemaBase>;

package/src/validations/queue/queueAmd.validations.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+import { flexibleLookupSchema } from '../_shared/lookup.validations';
+
+/** Answering-machine detection, on the outbound IVR and the two auto-dialers. */
+export const queueAmdSchema = z.object({
+	enabled: z.boolean().optional(),
+	ai: z.boolean().optional(),
+	positive: z.array(z.string()).optional(),
+	playback: flexibleLookupSchema.optional(),
+	allowNotSure: z.boolean().optional(),
+	silenceNotSure: z.boolean().optional(),
+	maxWordLength: z.number().optional(),
+	maxNumberOfWords: z.number().optional(),
+	betweenWordsSilence: z.number().optional(),
+	minWordLength: z.number().optional(),
+	totalAnalysisTime: z.number().optional(),
+	silenceThreshold: z.number().optional(),
+	afterGreetingSilence: z.number().optional(),
+	greeting: z.number().optional(),
+	initialSilence: z.number().optional(),
+});

package/src/validations/queue/queuePayload.validations.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+
+import { queueAmdSchema } from './queueAmd.validations';
+
+/**
+ * @description
+ * The union of every queue type's `payload`. Which of these a given queue
+ * actually uses is decided by its type, both for display (the admin app's
+ * `QueueTypeProperties` lookup) and for validation (`queueTypeRules`).
+ *
+ * Deliberately no `.default()` on any leaf. Defaults come from
+ * `getQueueDefaults(type)`, which holds exactly the per-type key set; a default
+ * here would seed every queue with every field, and since
+ * `sanitize(fieldsToSend)` only filters top-level keys, `payload` is sent
+ * whole — an inbound queue would ship `progressiveCount` to the backend.
+ */
+export const queuePayloadSchema = z.object({
+	// dialing and retries
+	maxAttempts: z.number().optional(),
+	minAttempts: z.number().optional(),
+	originateTimeout: z.number().optional(),
+	waitBetweenRetries: z.number().optional(),
+	waitBetweenRetriesDesc: z.boolean().optional(),
+	minDuration: z.number().optional(),
+	maxCalls: z.number().optional(),
+	progressiveCount: z.number().optional(),
+	dialingRate: z.number().optional(),
+	resourceStrategy: z.string().optional(),
+	strictCircuit: z.boolean().optional(),
+	perNumbers: z.boolean().optional(),
+	endless: z.boolean().optional(),
+	retryAbandoned: z.boolean().optional(),
+
+	// predictive dialer only
+	maxAgentLine: z.number().optional(),
+	maxAgentLose: z.number().optional(),
+	maxAbandonedRate: z.number().optional(),
+	targetAbandonedRate: z.number().optional(),
+	abandonRateAdjustment: z.number().optional(),
+	loadFactor: z.number().optional(),
+	playbackSilence: z.number().optional(),
+	statisticTime: z.number().optional(),
+
+	// waiting and distribution
+	timeBaseScore: z.string().optional(),
+	maxWaitTime: z.number().optional(),
+	maxWaitingSize: z.number().optional(),
+	discardAbandonedAfter: z.number().optional(),
+	manualDistribution: z.boolean().optional(),
+	minOnlineAgents: z.number().optional(),
+	maxMemberLimit: z.number().optional(),
+	ignoreCalendar: z.boolean().optional(),
+
+	// sticky agent
+	stickyAgentSec: z.number().optional(),
+	stickyIgnoreStatus: z.boolean().optional(),
+
+	// chat queues only
+	maxIdleAgent: z.number().optional(),
+	maxIdleClient: z.number().optional(),
+	maxIdleDialog: z.number().optional(),
+	lastMessageTimeout: z.boolean().optional(),
+
+	// media
+	recordings: z.boolean().optional(),
+	recordAll: z.boolean().optional(),
+	allowGreetingAgent: z.boolean().optional(),
+	autoAnswerTone: z.string().nullable().optional(),
+
+	amd: queueAmdSchema.optional(),
+});

package/src/validations/queue/taskProcessing.validations.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+import { flexibleLookupSchema } from '../_shared/lookup.validations';
+
+export const prolongationOptionsSchema = z.object({
+	enabled: z.boolean().optional(),
+	isTimeoutRetry: z.boolean().optional(),
+	prolongationTimeSec: z.number().optional(),
+	repeatsNumber: z.number().optional(),
+});
+
+export const taskProcessingSchema = z.object({
+	enabled: z.boolean().optional(),
+	formSchema: flexibleLookupSchema.optional(),
+	sec: z.number().optional(),
+	renewalSec: z.number().optional(),
+	// `.prefault`, not `.default`: zod 4's `.default({})` does not recurse, so
+	// the nested keys would be missing and Regle would build no `$fields` for
+	// them — the prolongation block would lose its validation silently.
+	prolongationOptions: prolongationOptionsSchema.prefault({}),
+});

package/src/validations/queueBucket/queueBucket.validations.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+import { filledLookupSchema } from '../_shared/lookup.validations';
+
+export const queueBucketSchema = z.object({
+	bucket: filledLookupSchema,
+	/** legacy: required + numeric + minValue(0) */
+	priority: z.number().min(0),
+	disabled: z.boolean().optional(),
+});

package/src/validations/queueHook/queueHook.validations.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+import { filledLookupSchema } from '../_shared/lookup.validations';
+
+export const queueHookSchema = z.object({
+	event: z.string().min(1),
+	schema: filledLookupSchema,
+	properties: z.array(z.string()).optional(),
+	enabled: z.boolean().optional(),
+});

package/src/validations/queueMember/memberCommunication.validations.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+import {
+	filledLookupSchema,
+	flexibleLookupSchema,
+} from '../_shared/lookup.validations';
+
+/**
+ * Carried over verbatim from the admin app's `digitsDtmfOnly` validator.
+ *
+ * NB the character class allows a literal `|` as well as digits and `w`/`W` —
+ * `[\d|w|W]` was almost certainly meant to be `[\dwW]`. Preserved as-is:
+ * tightening it would start rejecting values that save today.
+ */
+const dtmfPattern = /^[\d|w|W]*$/;
+
+export const memberCommunicationSchema = z.object({
+	destination: z.string().min(1),
+	type: filledLookupSchema,
+	dtmf: z.string().regex(dtmfPattern).optional(),
+	display: z.string().optional(),
+	priority: z.number().optional(),
+	resource: flexibleLookupSchema.optional(),
+	description: z.string().optional(),
+});

package/src/validations/queueMember/queueMember.validations.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+import { flexibleLookupSchema } from '../_shared/lookup.validations';
+import { variablePairSchema } from '../_shared/variablePair.validations';
+import { memberCommunicationSchema } from './memberCommunication.validations';
+
+/**
+ * @description
+ * A queue member.
+ *
+ * `communications` and `variables` must stay in the schema even though neither
+ * is validated beyond "at least one communication": the card store saves the
+ * schema's parsed output, so a key that is absent here is a key that never
+ * reaches the backend.
+ */
+export const queueMemberSchema = z.object({
+	name: z.string().min(1),
+	/** legacy `requiredArrayValue` — a member with no way to reach it is useless */
+	communications: z.array(memberCommunicationSchema).min(1),
+	priority: z.number().optional(),
+	bucket: flexibleLookupSchema.optional(),
+	timezone: flexibleLookupSchema.optional(),
+	agent: flexibleLookupSchema.optional(),
+	expireAt: z
+		.union([
+			z.string(),
+			z.number(),
+		])
+		.optional(),
+	minOfferingAt: z
+		.union([
+			z.string(),
+			z.number(),
+		])
+		.optional(),
+	stopCause: z.string().optional(),
+	variables: z.array(variablePairSchema).optional(),
+});

package/src/validations/queueResGroup/queueResGroup.validations.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+import {
+	filledLookupSchema,
+	flexibleLookupSchema,
+} from '../_shared/lookup.validations';
+
+export const queueResGroupSchema = z.object({
+	resourceGroup: filledLookupSchema,
+	/**
+	 * Sent, but never edited — the popup has no control for it. Kept so it
+	 * survives a round-trip rather than being stripped on save.
+	 */
+	communication: flexibleLookupSchema.optional(),
+});

package/src/validations/queueSkill/queueSkill.validations.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+
+import {
+	filledLookupSchema,
+	flexibleLookupSchema,
+} from '../_shared/lookup.validations';
+
+export const queueSkillSchemaBase = z.object({
+	skill: filledLookupSchema,
+	lvl: z.number().min(0).max(1000),
+	minCapacity: z.number().min(0).max(100).optional(),
+	maxCapacity: z.number().min(0).max(100).optional(),
+	buckets: z.array(flexibleLookupSchema).optional(),
+	enabled: z.boolean().optional(),
+});
+
+/**
+ * `minCapacity` and `maxCapacity` bound each other, which Vuelidate expressed
+ * as a pair of cross-field validators. Both sides are reported, so whichever
+ * field the user is editing shows the error.
+ */
+export const queueSkillSchema = queueSkillSchemaBase.superRefine(
+	(skill, ctx) => {
+		if (skill.minCapacity == null || skill.maxCapacity == null) return;
+		if (skill.minCapacity <= skill.maxCapacity) return;
+
+		ctx.addIssue({
+			code: 'custom',
+			path: [
+				'minCapacity',
+			],
+			message: 'Value must be less than or equal to the maximum capacity',
+		});
+		ctx.addIssue({
+			code: 'custom',
+			path: [
+				'maxCapacity',
+			],
+			message: 'Value must be greater than or equal to the minimum capacity',
+		});
+	},
+);