feat(frontend): Service to call the transfer method of EXT token canister (#10627)

# Motivation

Like the other methods, we create an API service to call method
`transfer` of `ExtV2TokenCanister`.

Author: AntonioVentilii

src/frontend/src/icp/api/ext-v2-token.api.ts

@@ -47,7 +47,7 @@ export const transactions = async ({
  * @param {boolean} [params.certified=true] - Whether the data should be certified.
  * @param {OptionIdentity} params.identity - The identity to use for the request.
  * @param {CanisterIdText} params.canisterId - The canister ID of the EXT v2 token.
- * @param {TokenIdentifier} params.tokenIdentifier - The token identifier as string.
+ * @param {TokenIdentifier} params.tokenIdentifier - The token identifier of the NFT as string.
  * @param {QueryParams} params.rest - Additional query parameters.
  * @returns {Promise<Balance>} The user's balance for the specified token.
  */
@@ -82,17 +82,17 @@ export const balance = async ({
  * @link https://github.com/Toniq-Labs/ext-v2-token/blob/main/API-REFERENCE.md#tokens_ext
  *
  * @param {Object} params - The parameters for fetching the tokens.
- * @param {Principal} params.owner - The principal of the owner whose tokens should be fetched.
+ * @param {boolean} [params.certified=true] - Whether the data should be certified.
  * @param {OptionIdentity} params.identity - The identity to use for the request.
  * @param {CanisterIdText} params.canisterId - The canister ID of the EXT v2 token.
- * @param {boolean} [params.certified=true] - Whether the data should be certified.
+ * @param {Principal} params.owner - The principal of the owner whose tokens should be fetched.
  * @returns {Promise<TokenIndex[]>} The list of token indices owned by the user.
  * @throws CanisterInternalError if the token identifier is invalid.
  */
 export const getTokensByOwner = async ({
+	certified,
 	identity,
 	owner,
-	certified,
 	canisterId,
 	...rest
 }: CanisterApiFunctionParamsWithCanisterId<{ owner: Principal } & QueryParams>): Promise<
@@ -111,6 +111,41 @@ export const getTokensByOwner = async ({
 	return await getTokensByOwner({ certified, ...getIcrcAccount(owner) });
 };
 
+/**
+ * Transfer NFT of a collection from one user to another.
+ *
+ * @link https://github.com/Toniq-Labs/ext-v2-token/blob/main/API-REFERENCE.md#transfer--ext_transfer
+ *
+ * @param {Object} params - The parameters for the transfer.
+ * @param {boolean} [params.certified=true] - Whether the data should be certified.
+ * @param {OptionIdentity} params.identity - The identity to use for the request.
+ * @param {CanisterIdText} params.canisterId - The canister ID of the EXT v2 token.
+ * @param {Principal} params.from - The ICRC principal of the sender.
+ * @param {Principal} params.to - The ICRC principal of the receiver.
+ * @param {TokenIdentifier} params.tokenIdentifier - The token identifier of the NFT as string.
+ * @param {bigint} params.amount - The amount to transfer.
+ */
+export const transfer = async ({
+	certified,
+	identity,
+	canisterId,
+	from,
+	to,
+	tokenIdentifier,
+	amount,
+	...rest
+}: CanisterApiFunctionParamsWithCanisterId<
+	{ from: Principal; to: Principal; tokenIdentifier: TokenIdentifier; amount: bigint } & QueryParams
+>) => {
+	const { transfer } = await extV2TokenCanister({
+		identity,
+		canisterId,
+		...rest
+	});
+
+	await transfer({ certified, from, to, tokenIdentifier, amount });
+};
+
 const extV2TokenCanister = async ({
 	identity,
 	nullishIdentityErrorMessage,

src/frontend/src/tests/icp/api/ext-v2-token.api.spec.ts

@@ -1,12 +1,12 @@
-import { balance, getTokensByOwner, transactions } from '$icp/api/ext-v2-token.api';
+import { balance, getTokensByOwner, transactions, transfer } from '$icp/api/ext-v2-token.api';
 import { ExtV2TokenCanister } from '$icp/canisters/ext-v2-token.canister';
 import { ZERO } from '$lib/constants/app.constants';
 import {
 	mockExtV2TokenCanisterId,
 	mockExtV2TokenIdentifier,
 	mockExtV2Transactions
 } from '$tests/mocks/ext-v2-token.mock';
-import { mockIdentity, mockPrincipal } from '$tests/mocks/identity.mock';
+import { mockIdentity, mockPrincipal, mockPrincipal2 } from '$tests/mocks/identity.mock';
 import { mock } from 'vitest-mock-extended';
 
 describe('ext-v2-token.api', () => {
@@ -111,4 +111,42 @@ describe('ext-v2-token.api', () => {
 			expect(tokenCanisterMock.getTokensByOwner).not.toHaveBeenCalled();
 		});
 	});
+
+	describe('transfer', () => {
+		const mockBalance = 456n;
+
+		const params = {
+			identity: mockIdentity,
+			canisterId: mockExtV2TokenCanisterId,
+			from: mockPrincipal,
+			to: mockPrincipal2,
+			tokenIdentifier: mockExtV2TokenIdentifier,
+			amount: 123n
+		};
+
+		const expectedParams = {
+			from: mockPrincipal,
+			to: mockPrincipal2,
+			tokenIdentifier: mockExtV2TokenIdentifier,
+			amount: 123n
+		};
+
+		beforeEach(() => {
+			tokenCanisterMock.transfer.mockResolvedValue(mockBalance);
+		});
+
+		it('should call successfully transfer endpoint', async () => {
+			await transfer(params);
+
+			expect(tokenCanisterMock.transfer).toHaveBeenCalledExactlyOnceWith(expectedParams);
+		});
+
+		it('should raise an error if identity is nullish', async () => {
+			await expect(transfer({ ...params, identity: undefined })).rejects.toThrow();
+
+			await expect(transfer({ ...params, identity: null })).rejects.toThrow();
+
+			expect(tokenCanisterMock.transfer).not.toHaveBeenCalled();
+		});
+	});
 });