@webitel/api-services 0.1.69 → 0.1.70

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webitel/api-services",
-	"version": "0.1.69",
+	"version": "0.1.70",
 	"private": false,
 	"repository": {
 		"type": "git",
@@ -39,6 +39,7 @@
 		"CHANGELOG.md"
 	],
 	"peerDependencies": {
+		"date-fns": "^4.1.0",
 		"deep-copy": "^1.4.2",
 		"deep-equal": "^2.2.3",
 		"deepmerge": "^4.3.1",
@@ -51,6 +52,7 @@
 		"@types/node": "^22.13.10",
 		"axios": "^1.15.2",
 		"change-case": "^5.4.4",
+		"date-fns": "^4.1.0",
 		"globby": "^14.1.0",
 		"husky": "^9.1.7",
 		"is-json": "^2.0.1",

package/src/api/clients/_shared/types.ts

@@ -32,3 +32,28 @@ export interface PatchItemParams {
 export interface DeleteItemParams {
 	id: ApiId;
 }
+
+/**
+ * Params for entities that only exist under a parent — queue hooks, skills,
+ * buckets, resource groups, members. ui-datalist threads `parentId` through
+ * every call a nested table or its card popup makes.
+ */
+export interface NestedGetItemParams extends GetItemParams {
+	parentId: ApiId;
+}
+
+export interface NestedAddItemParams extends AddItemParams {
+	parentId: ApiId;
+}
+
+export interface NestedUpdateItemParams extends UpdateItemParams {
+	parentId: ApiId;
+}
+
+export interface NestedPatchItemParams extends PatchItemParams {
+	parentId: ApiId;
+}
+
+export interface NestedDeleteItemParams extends DeleteItemParams {
+	parentId: ApiId;
+}

package/src/api/clients/index.ts

@@ -37,6 +37,14 @@ export * from './object/object';
 export * from './onlineSkills/onlineSkills';
 export * from './pdfServices/pdfServices';
 export * from './phones/phones';
+export * from './queues/queueAgents';
+export * from './queues/queueBuckets';
+export * from './queues/queueHooks';
+export * from './queues/queueLogs';
+export * from './queues/queueMembers';
+export * from './queues/queueResGroups';
+export * from './queues/queueSkills';
+export * from './queues/queueState';
 export * from './queues/queues';
 export * from './quickReplies/quickReplies';
 export * from './regions/regions';

package/src/api/clients/queues/__tests__/fieldsToSend.spec.ts

@@ -0,0 +1,135 @@
+import { getShallowFieldsToSendFromZodSchema } from '@webitel/api-services/gen/utils';
+import { describe, expect, it } from 'vitest';
+
+import {
+	queueBucketSchema,
+	queueHookSchema,
+	queueMemberSchema,
+	queueResGroupSchema,
+	queueSchema,
+	queueSkillSchema,
+} from '../../../../validations';
+
+/**
+ * The queue api modules derive their `sanitize()` whitelists from these
+ * schemas, so the form and the request cannot drift apart. That only holds
+ * while `getShallowFieldsToSendFromZodSchema` can still read the keys — and
+ * `queueSchema` and `queueSkillSchema` are `superRefine`-wrapped, which would
+ * hide them if zod ever moved refinements back outside the object.
+ */
+const fieldsOf = (
+	schema: Parameters<typeof getShallowFieldsToSendFromZodSchema>[0],
+) =>
+	[
+		...getShallowFieldsToSendFromZodSchema(schema),
+	].sort();
+
+describe('fields derived from the queue schemas', () => {
+	it('sends every editable queue field', () => {
+		expect(fieldsOf(queueSchema)).toEqual([
+			'afterSchema',
+			'calendar',
+			'description',
+			'dncList',
+			'doSchema',
+			'enabled',
+			'formSchema',
+			'grantee',
+			'name',
+			'payload',
+			'priority',
+			'ringtone',
+			'schema',
+			'stickyAgent',
+			'strategy',
+			'tags',
+			'taskProcessing',
+			'team',
+			'type',
+			'variables',
+		]);
+	});
+
+	it('reads through the queue superRefine', () => {
+		// the rules wrapper must not hide the shape from the whitelist
+		expect(fieldsOf(queueSchema)).toContain('payload');
+		expect(fieldsOf(queueSkillSchema)).toContain('skill');
+	});
+
+	it.each([
+		[
+			'hook',
+			queueHookSchema,
+			[
+				'enabled',
+				'event',
+				'properties',
+				'schema',
+			],
+		],
+		[
+			'bucket',
+			queueBucketSchema,
+			[
+				'bucket',
+				'disabled',
+				'priority',
+			],
+		],
+		[
+			'resource group',
+			queueResGroupSchema,
+			[
+				'communication',
+				'resourceGroup',
+			],
+		],
+		[
+			'skill',
+			queueSkillSchema,
+			[
+				'buckets',
+				'enabled',
+				'lvl',
+				'maxCapacity',
+				'minCapacity',
+				'skill',
+			],
+		],
+		[
+			'member',
+			queueMemberSchema,
+			[
+				'agent',
+				'bucket',
+				'communications',
+				'expireAt',
+				'minOfferingAt',
+				'name',
+				'priority',
+				'stopCause',
+				'timezone',
+				'variables',
+			],
+		],
+	])('sends every editable %s field', (_entity, schema, expected) => {
+		expect(fieldsOf(schema)).toEqual(expected);
+	});
+
+	/**
+	 * `queueId` is put on nested bodies by each module's `preRequestHandler`; it
+	 * belongs to the url, not the form, so it is appended to the derived list
+	 * rather than added to the schema.
+	 */
+	it('leaves queueId out of the nested schemas', () => {
+		for (const schema of [
+			queueHookSchema,
+			queueBucketSchema,
+			queueResGroupSchema,
+			queueSkillSchema,
+			queueMemberSchema,
+		]) {
+			expect(fieldsOf(schema)).not.toContain('queueId');
+		}
+	});
+});

package/src/api/clients/queues/__tests__/queueLogs.spec.ts

@@ -0,0 +1,132 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const searchAttemptsHistory = vi.fn();
+
+vi.mock('@webitel/api-services/gen', () => ({
+	getMemberService: () => ({
+		searchAttemptsHistory,
+	}),
+}));
+
+const { QueueLogsAPI } = await import('../queueLogs');
+
+const paramsSent = () => searchAttemptsHistory.mock.calls[0][0];
+
+describe('QueueLogsAPI.getList', () => {
+	beforeEach(() => {
+		searchAttemptsHistory.mockReset().mockResolvedValue({
+			data: {
+				items: [],
+				next: false,
+			},
+		});
+	});
+
+	/**
+	 * The range filters are protobuf nested messages, so they only bind as
+	 * `joined_at.from`. The generated params type calls them `joinedAtFrom`,
+	 * which the backend would ignore — the request would succeed and quietly
+	 * return unfiltered rows. That is how the duration filter was broken before
+	 * this migration, so it is worth pinning.
+	 *
+	 * Verified live: `joined_at`, `leaving_at` and `offering_at` all filter with
+	 * this shape. `duration` does not — the backend accepts and ignores it (see
+	 * the note in `queueLogs.ts`), so this pins the wire format only, not that
+	 * the duration filter actually works.
+	 */
+	it('sends range bounds as dotted keys', async () => {
+		await QueueLogsAPI.getList({
+			parentId: '7',
+			joinedAt: {
+				from: 100,
+				to: 200,
+			},
+			duration: {
+				from: 5,
+				to: 30,
+			},
+		});
+
+		expect(paramsSent()).toMatchObject({
+			'joined_at.from': 100,
+			'joined_at.to': 200,
+			'duration.from': 5,
+			'duration.to': 30,
+		});
+	});
+
+	it('does not send the flattened names the generated type declares', async () => {
+		await QueueLogsAPI.getList({
+			parentId: '7',
+			joinedAt: {
+				from: 100,
+				to: 200,
+			},
+		});
+
+		expect(paramsSent()).not.toHaveProperty('joinedAtFrom');
+		expect(paramsSent()).not.toHaveProperty('joinedAtTo');
+	});
+
+	it('maps the filter names onto the service params', async () => {
+		await QueueLogsAPI.getList({
+			parentId: '7',
+			bucket: [
+				1,
+			],
+			agent: [
+				2,
+			],
+			leavingAt: {
+				from: 10,
+				to: 20,
+			},
+			offeringAt: {
+				from: 30,
+				to: 40,
+			},
+		});
+
+		expect(paramsSent()).toMatchObject({
+			bucketId: [
+				1,
+			],
+			agentId: [
+				2,
+			],
+			'leaving_at.from': 10,
+			'leaving_at.to': 20,
+			'offering_at.from': 30,
+			'offering_at.to': 40,
+		});
+	});
+
+	it('scopes the query to its queue and maps search onto q', async () => {
+		await QueueLogsAPI.getList({
+			parentId: '7',
+			search: 'joe',
+		});
+
+		// `starToSearch` makes it a prefix search, as everywhere else
+		expect(paramsSent()).toMatchObject({
+			queueId: [
+				'7',
+			],
+			q: 'joe*',
+		});
+	});
+
+	it('sorts by join time unless told otherwise', async () => {
+		await QueueLogsAPI.getList({
+			parentId: '7',
+		});
+		expect(paramsSent().sort).toBe('+joined_at');
+
+		searchAttemptsHistory.mockClear();
+		await QueueLogsAPI.getList({
+			parentId: '7',
+			sort: '-duration',
+		});
+		expect(paramsSent().sort).toBe('-duration');
+	});
+});

package/src/api/clients/queues/__tests__/queueMembers.spec.ts

@@ -0,0 +1,175 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const searchMemberInQueue = vi.fn();
+const resetMembersCount = vi.fn();
+const resetMembers = vi.fn();
+
+vi.mock('@webitel/api-services/gen', () => ({
+	getMemberService: () => ({
+		searchMemberInQueue,
+		resetMembersCount,
+		resetMembers,
+	}),
+}));
+
+const { QueueMembersAPI } = await import('../queueMembers');
+
+describe('QueueMembersAPI.getList', () => {
+	beforeEach(() => {
+		searchMemberInQueue.mockReset().mockResolvedValue({
+			data: {
+				items: [],
+				next: false,
+			},
+		});
+	});
+
+	const paramsSent = () => searchMemberInQueue.mock.calls[0][1];
+
+	/**
+	 * `created_at` and `priority` are protobuf nested messages, so they only
+	 * bind as dotted keys. The generated params type calls them `createdAtFrom`
+	 * and `priorityFrom`, which the backend ignores — the request succeeds and
+	 * returns unfiltered rows.
+	 */
+	it('sends range bounds as dotted keys', async () => {
+		await QueueMembersAPI.getList({
+			parentId: '7',
+			createdAt: {
+				from: 100,
+				to: 200,
+			},
+			memberPriority: {
+				from: 1,
+				to: 9,
+			},
+		});
+
+		expect(paramsSent()).toMatchObject({
+			'created_at.from': 100,
+			'created_at.to': 200,
+			'priority.from': 1,
+			'priority.to': 9,
+		});
+		expect(paramsSent()).not.toHaveProperty('createdAtFrom');
+		expect(paramsSent()).not.toHaveProperty('priorityFrom');
+	});
+
+	it('passes the queue id positionally, as a number', async () => {
+		await QueueMembersAPI.getList({
+			parentId: '7',
+		});
+
+		expect(searchMemberInQueue.mock.calls[0][0]).toBe(7);
+	});
+
+	/** the datalist names differ from the service's, so the mapping is explicit */
+	it('maps the filter names onto the service params', async () => {
+		await QueueMembersAPI.getList({
+			parentId: '7',
+			search: 'joe',
+			bucket: [
+				1,
+			],
+			agent: [
+				2,
+			],
+			stopCause: [
+				'cancel',
+			],
+			offeringAt: {
+				from: 300,
+				to: 400,
+			},
+			attempts: {
+				from: 2,
+				to: 5,
+			},
+			name: 'alice',
+			destination: '380',
+		});
+
+		expect(paramsSent()).toMatchObject({
+			q: 'joe*',
+			bucketId: [
+				1,
+			],
+			agentId: [
+				2,
+			],
+			stopCause: [
+				'cancel',
+			],
+			'offering_at.from': 300,
+			'offering_at.to': 400,
+			'attempts.from': 2,
+			'attempts.to': 5,
+			name: 'alice',
+			destination: '380',
+		});
+	});
+
+	/** the pre-migration spellings still work, so both can coexist */
+	it('still accepts the legacy filter names', async () => {
+		await QueueMembersAPI.getList({
+			parentId: '7',
+			from: 100,
+			to: 200,
+			cause: [
+				'cancel',
+			],
+		});
+
+		expect(paramsSent()).toMatchObject({
+			'created_at.from': 100,
+			'created_at.to': 200,
+			stopCause: [
+				'cancel',
+			],
+		});
+	});
+});
+
+describe('QueueMembersAPI.getQuantity', () => {
+	beforeEach(() => {
+		resetMembersCount.mockReset().mockResolvedValue({
+			data: {
+				count: 12,
+			},
+		});
+	});
+
+	/** was a hand-built url; the generated call must keep the dotted keys */
+	it('counts through the service with dotted range keys', async () => {
+		const count = await QueueMembersAPI.getQuantity({
+			parentId: '7',
+			filters: {
+				createdAt: {
+					from: 100,
+					to: 200,
+				},
+			},
+		});
+
+		expect(count).toBe(12);
+		expect(resetMembersCount).toHaveBeenCalledWith(
+			'7',
+			expect.objectContaining({
+				'created_at.from': 100,
+				'created_at.to': 200,
+			}),
+		);
+	});
+
+	it('reports zero when the service returns no count', async () => {
+		resetMembersCount.mockResolvedValue({
+			data: {},
+		});
+
+		await expect(
+			QueueMembersAPI.getQuantity({
+				parentId: '7',
+			}),
+		).resolves.toBe(0);
+	});
+});

package/src/api/clients/queues/__tests__/queues.spec.ts

@@ -0,0 +1,130 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { QueueType } from '../../../../enums';
+
+const readQueue = vi.fn();
+const searchQueue = vi.fn();
+
+vi.mock('@webitel/api-services/gen', () => ({
+	getQueueService: () => ({
+		readQueue,
+		searchQueue,
+	}),
+}));
+
+const { QueuesAPI } = await import('../queues');
+
+/**
+ * proto3 omits zero values, so an OFFLINE_QUEUE (type `0`) arrives with no
+ * `type` key at all. Legacy restored it with a `defaultObject`; these tests
+ * pin that the restore survived the migration.
+ *
+ * The failure mode is silent and severe: without `type`, `getQueueDefaults`
+ * falls back to the type-agnostic base, the Params tab renders none of the
+ * offline-specific controls, and `queueSchema`'s `superRefine` skips the
+ * per-type branch — the form just quietly loses half its behaviour.
+ */
+describe('QueuesAPI.get, on a type-less (offline) response', () => {
+	beforeEach(() => {
+		readQueue.mockReset();
+	});
+
+	it('restores type 0 and seeds the offline defaults', async () => {
+		readQueue.mockResolvedValue({
+			data: {
+				id: 239,
+				name: 'offline',
+				payload: {},
+			},
+		});
+
+		const item = await QueuesAPI.get({
+			itemId: 239,
+		});
+
+		expect(item.type).toBe(QueueType.OFFLINE_QUEUE);
+		// seeded from offlineQueue(), not from the base defaults
+		expect(item.payload).toMatchObject({
+			maxAttempts: 3,
+			originateTimeout: 60,
+			minOnlineAgents: 0,
+		});
+		expect(item.taskProcessing).toBeDefined();
+	});
+
+	it('never overwrites a type the backend did send', async () => {
+		readQueue.mockResolvedValue({
+			data: {
+				id: 15,
+				type: QueueType.CHAT_INBOUND_QUEUE,
+				payload: {},
+			},
+		});
+
+		const item = await QueuesAPI.get({
+			itemId: 15,
+		});
+
+		expect(item.type).toBe(QueueType.CHAT_INBOUND_QUEUE);
+	});
+});
+
+describe('QueuesAPI.getList, on type-less rows', () => {
+	beforeEach(() => {
+		searchQueue.mockReset();
+	});
+
+	/**
+	 * The table renders `type`, `active` and `waiting` straight into cells, so
+	 * an omitted zero shows up as a blank column rather than "Offline queue"/0.
+	 */
+	it('restores the zero values the table renders', async () => {
+		searchQueue.mockResolvedValue({
+			data: {
+				items: [
+					{
+						id: 239,
+						name: 'offline',
+					},
+				],
+				next: false,
+			},
+		});
+
+		const { items } = await QueuesAPI.getList({});
+
+		expect(items[0]).toMatchObject({
+			type: QueueType.OFFLINE_QUEUE,
+			enabled: false,
+			active: 0,
+			waiting: 0,
+		});
+	});
+
+	it('leaves non-zero values alone', async () => {
+		searchQueue.mockResolvedValue({
+			data: {
+				items: [
+					{
+						id: 15,
+						type: QueueType.CHAT_INBOUND_QUEUE,
+						enabled: true,
+						active: 4,
+						priority: 1000,
+					},
+				],
+				next: false,
+			},
+		});
+
+		const { items } = await QueuesAPI.getList({});
+
+		expect(items[0]).toMatchObject({
+			type: QueueType.CHAT_INBOUND_QUEUE,
+			enabled: true,
+			active: 4,
+			priority: 1000,
+			waiting: 0,
+		});
+	});
+});