LW-12083 feat(cardano-services-client): restore KoraLabsHandleProvider

packages/cardano-services-client/package.json

@@ -60,6 +60,7 @@
     "@cardano-sdk/core": "workspace:~",
     "@cardano-sdk/crypto": "workspace:~",
     "@cardano-sdk/util": "workspace:~",
+    "@koralabs/handles-public-api-interfaces": "^2.13.0",
     "axios": "^1.7.4",
     "class-validator": "^0.14.0",
     "isomorphic-ws": "^5.0.0",

packages/cardano-services-client/src/HandleProvider/KoraLabsHandleProvider.ts

@@ -0,0 +1,96 @@
+import {
+  Asset,
+  Cardano,
+  HandleProvider,
+  HandleResolution,
+  HealthCheckResponse,
+  ProviderError,
+  ProviderFailure,
+  ResolveHandlesArgs
+} from '@cardano-sdk/core';
+
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { IHandle } from '@koralabs/handles-public-api-interfaces';
+import axios, { AxiosAdapter, AxiosInstance } from 'axios';
+
+/** The KoraLabsHandleProvider endpoint paths. */
+const paths = {
+  handles: '/handles',
+  healthCheck: '/health'
+};
+
+export interface KoraLabsHandleProviderDeps {
+  serverUrl: string;
+  adapter?: AxiosAdapter;
+  policyId: Cardano.PolicyId;
+}
+
+export const toHandleResolution = ({
+  apiResponse,
+  policyId
+}: {
+  apiResponse: IHandle;
+  policyId: Cardano.PolicyId;
+}): HandleResolution => ({
+  backgroundImage: apiResponse.bg_image ? Asset.Uri(apiResponse.bg_image) : undefined,
+  cardanoAddress: Cardano.PaymentAddress(apiResponse.resolved_addresses.ada),
+  handle: apiResponse.name,
+  hasDatum: apiResponse.has_datum,
+  image: apiResponse.image ? Asset.Uri(apiResponse.image) : undefined,
+  policyId,
+  profilePic: apiResponse.pfp_image ? Asset.Uri(apiResponse.pfp_image) : undefined
+});
+
+/**
+ * Creates a KoraLabs Provider instance to resolve Standard Handles
+ *
+ * @param KoraLabsHandleProviderDeps The configuration object fot the KoraLabs Handle Provider.
+ */
+export class KoraLabsHandleProvider implements HandleProvider {
+  private axiosClient: AxiosInstance;
+  policyId: Cardano.PolicyId;
+
+  constructor({ serverUrl, adapter, policyId }: KoraLabsHandleProviderDeps) {
+    this.axiosClient = axios.create({
+      adapter,
+      baseURL: serverUrl
+    });
+    this.policyId = policyId;
+  }
+
+  async resolveHandles(args: ResolveHandlesArgs): Promise<Array<HandleResolution | null>> {
+    try {
+      const results = await Promise.all(
+        args.handles.map((handle) => this.axiosClient.get<IHandle>(`${paths.handles}/${handle}`))
+      );
+      return results.map(({ data: apiResponse }) => toHandleResolution({ apiResponse, policyId: this.policyId }));
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        if (error.request) {
+          throw new ProviderError(ProviderFailure.ConnectionFailure, error, error.code);
+        }
+
+        if (error.response?.status === 404) {
+          return [null];
+        }
+
+        throw new ProviderError(ProviderFailure.Unhealthy, error, `Failed to resolve handles due to: ${error.message}`);
+      }
+      if (error instanceof ProviderError) throw error;
+      throw new ProviderError(ProviderFailure.Unknown, error, 'Failed to resolve handles');
+    }
+  }
+
+  async healthCheck(): Promise<HealthCheckResponse> {
+    try {
+      await this.axiosClient.get(`${paths.healthCheck}`);
+      return { ok: true };
+    } catch {
+      return { ok: false };
+    }
+  }
+
+  async getPolicyIds(): Promise<Cardano.PolicyId[]> {
+    return [this.policyId];
+  }
+}

packages/cardano-services-client/src/HandleProvider/index.ts

@@ -1 +1,2 @@
+export * from './KoraLabsHandleProvider';
 export * from './handleHttpProvider';

packages/cardano-services-client/test/HandleProvider/KoraLabsHandleProvider.test.ts

@@ -0,0 +1,109 @@
+/* eslint-disable no-magic-numbers */
+/* eslint-disable camelcase */
+import { Cardano, ProviderError } from '@cardano-sdk/core';
+import { KoraLabsHandleProvider } from '../../src';
+import {
+  getAliceHandleAPIResponse,
+  getAliceHandleProviderResponse,
+  getBobHandleAPIResponse,
+  getBobHandleProviderResponse
+} from '../util';
+import MockAdapter from 'axios-mock-adapter';
+import axios from 'axios';
+
+const config = {
+  policyId: Cardano.PolicyId('50fdcdbfa3154db86a87e4b5697ae30d272e0bbcfa8122efd3e301cb'),
+  serverUrl: 'http://some-hostname:3000'
+};
+
+describe('KoraLabsHandleProvider', () => {
+  let axiosMock: MockAdapter;
+  let provider: KoraLabsHandleProvider;
+
+  beforeAll(() => {
+    axiosMock = new MockAdapter(axios);
+    provider = new KoraLabsHandleProvider(config);
+  });
+
+  afterEach(() => {
+    axiosMock.reset();
+  });
+
+  afterAll(() => {
+    axiosMock.restore();
+  });
+
+  describe('resolveHandles', () => {
+    test('HandlesProvider should resolve a single handle', async () => {
+      axiosMock.onGet().replyOnce(200, getAliceHandleAPIResponse);
+      const args = {
+        handles: ['alice']
+      };
+      await expect(provider.resolveHandles(args)).resolves.toEqual([getAliceHandleProviderResponse]);
+    });
+
+    test('HandleProvider should resolve multiple handles', async () => {
+      axiosMock.onGet().replyOnce(200, getAliceHandleAPIResponse).onGet().replyOnce(200, getBobHandleAPIResponse);
+      const args = {
+        handles: ['alice', 'bob']
+      };
+      await expect(provider.resolveHandles(args)).resolves.toEqual([
+        getAliceHandleProviderResponse,
+        getBobHandleProviderResponse
+      ]);
+    });
+  });
+
+  describe('error checks', () => {
+    test('HandleProvider should throw ProviderError with ConnectionFailure on request error', async () => {
+      axiosMock.onGet('/handles/alice').networkError();
+      const args = { handles: ['alice'] };
+      await expect(provider.resolveHandles(args)).rejects.toThrowError(ProviderError);
+    });
+    test('HandleProvider should return null for 404 response from API', async () => {
+      axiosMock.onGet('/handles/alice').reply(404);
+      const args = { handles: ['alice'] };
+      await expect(provider.resolveHandles(args)).resolves.toEqual([null]);
+    });
+    test('HandleProvider should throw ProviderError with Unhealthy on other Axios error', async () => {
+      axiosMock.onGet('/handles/bob').reply(500);
+      const args = { handles: ['bob'] };
+      await expect(provider.resolveHandles(args)).rejects.toThrowError(ProviderError);
+    });
+    test('HandleProvider should throw ProviderError', async () => {
+      axiosMock.onGet('/handles/bob').networkError();
+      const args = { handles: ['bob'] };
+      await expect(provider.resolveHandles(args)).rejects.toThrowError(ProviderError);
+    });
+    test('HandleProvider should throw ProviderError with Unknown, unable to resolve handle', async () => {
+      axiosMock.onGet().replyOnce(304, getAliceHandleAPIResponse);
+      const args = { handles: ['bob'] };
+      await expect(provider.resolveHandles(args)).rejects.toThrowError(ProviderError);
+    });
+  });
+
+  describe('health checks', () => {
+    test('HandleProvider should get ok health check', async () => {
+      axiosMock.onGet().replyOnce(200, {});
+      const result = await provider.healthCheck();
+      expect(result.ok).toEqual(true);
+    });
+
+    test('HandleProvider should get not ok health check', async () => {
+      const providerWithBadConfig = new KoraLabsHandleProvider({
+        policyId: Cardano.PolicyId('50fdcdbfa3154db86a87e4b5697ae30d272e0bbcfa8122efd3e301cb'),
+        serverUrl: ''
+      });
+      const result = await providerWithBadConfig.healthCheck();
+      expect(result.ok).toEqual(false);
+    });
+  });
+
+  describe('get policy ids', () => {
+    test('HandleProvider should get handle policy ids', async () => {
+      const policyIds = await provider.getPolicyIds();
+      await expect(policyIds.length).toEqual(1);
+      await expect(policyIds).toEqual([config.policyId]);
+    });
+  });
+});

packages/cardano-services-client/test/util.ts

@@ -1,5 +1,6 @@
 import { Asset, Cardano, ProviderError, ProviderFailure } from '@cardano-sdk/core';
 import { AxiosError, AxiosResponse } from 'axios';
+import { IHandle, Rarity } from '@koralabs/handles-public-api-interfaces';
 import { logger } from '@cardano-sdk/util-dev';
 import { toSerializableObject } from '@cardano-sdk/util';
 
@@ -61,6 +62,50 @@ export const getBobHandleProviderResponse = {
   profilePic: Asset.Uri('ipfs://zrljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3yd1')
 };
 
+export const getAliceHandleAPIResponse: Partial<IHandle> = {
+  characters: 'rljm7n/23455',
+  created_slot_number: 33,
+  default_in_wallet: 'alice_default_hndle',
+  has_datum: false,
+  hex: '0f3abbc8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56fe0e78f19d9d5',
+  holder: 'stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw',
+  image: 'ipfs://c8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56feasd',
+  length: 123,
+  name: 'alice',
+  numeric_modifiers: '-12.9',
+  og_number: 5,
+  rarity: Rarity.rare,
+  resolved_addresses: {
+    ada: 'addr_test1qqk4sr4f7vtqzd2w90d5nfu3n59jhhpawyphnek2y7er02nkrezryq3ydtmkg0e7e2jvzg443h0ffzfwd09wpcxy2fuqmcnecd'
+  },
+  standard_image: 'ipfs://c8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56feasdfasd',
+  updated_slot_number: 22,
+  utxo: 'rljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3ydtmkg0'
+};
+
+export const getBobHandleAPIResponse: Partial<IHandle> = {
+  bg_image: 'ipfs://zrljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3yd',
+  characters: 'rljm7n/23455',
+  created_slot_number: 33,
+  default_in_wallet: 'bob_default_handle',
+  has_datum: false,
+  hex: '0f3abbc8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56fe0e78f19d9d5',
+  holder: 'stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw',
+  image: 'ipfs://c8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56fe',
+  length: 123,
+  name: 'bob',
+  numeric_modifiers: '-12.9',
+  og_number: 5,
+  pfp_image: 'ipfs://zrljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3yd1',
+  rarity: Rarity.rare,
+  resolved_addresses: {
+    ada: 'addr_test1qzrljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3ydtmkg0e7e2jvzg443h0ffzfwd09wpcxy2fuql9tk0g'
+  },
+  standard_image: 'ipfs://c8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56feasdfasd',
+  updated_slot_number: 22,
+  utxo: 'rljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3ydtmkg0'
+};
+
 export const mockResponses = (request: jest.Mock, responses: [string | RegExp, unknown][]) => {
   request.mockImplementation(async (endpoint: string) => {
     for (const [match, response] of responses) {

yarn-project.nix

@@ -493,6 +493,7 @@ cacheEntries = {
 "@jridgewell/trace-mapping@npm:0.3.25" = { filename = "@jridgewell-trace-mapping-npm-0.3.25-c076fd2279-9d3c40d225.zip"; sha512 = "9d3c40d225e139987b50c48988f8717a54a8c994d8a948ee42e1412e08988761d0754d7d10b803061cc3aebf35f92a5dbbab493bd0e1a9ef9e89a2130e83ba34"; };
 "@jridgewell/trace-mapping@npm:0.3.9" = { filename = "@jridgewell-trace-mapping-npm-0.3.9-91625cd7fb-d89597752f.zip"; sha512 = "d89597752fd88d3f3480845691a05a44bd21faac18e2185b6f436c3b0fd0c5a859fbbd9aaa92050c4052caf325ad3e10e2e1d1b64327517471b7d51babc0ddef"; };
 "@jsdevtools/ono@npm:7.1.3" = { filename = "@jsdevtools-ono-npm-7.1.3-cb2313543b-2297fcd472.zip"; sha512 = "2297fcd472ba810bffe8519d2249171132844c7174f3a16634f9260761c8c78bc0428a4190b5b6d72d45673c13918ab9844d706c3ed4ef8f62ab11a2627a08ad"; };
+"@koralabs/handles-public-api-interfaces@npm:2.13.0" = { filename = "@koralabs-handles-public-api-interfaces-npm-2.13.0-33d8afa484-b28895a70e.zip"; sha512 = "b28895a70ecdb1b4643953dd0af11b406970a5388b79889050f19ef01335c7da29fb8696d26e80f645fd435ca8cc90f13b5fed0c4a5ceb0ac0d2447aad5e3e06"; };
 "@ledgerhq/devices@npm:8.4.4" = { filename = "@ledgerhq-devices-npm-8.4.4-9331403bf0-370fb38d48.zip"; sha512 = "370fb38d484665c92165580e285cc792e7af0bf114a5d1e855aec602c6e39592090d0de7a43addeb4c13622f734ddd4f25be82f07507e14550753ce5473eea66"; };
 "@ledgerhq/errors@npm:6.19.1" = { filename = "@ledgerhq-errors-npm-6.19.1-4837ba7170-f4e1cf0d6a.zip"; sha512 = "f4e1cf0d6a5808c58235c54e2a1565556de8e683552bd94d97609f790e8c25226114bfa2af9914bb329c3e7c314585b60c66ddac8d8f8f1d072b7e791a889ad8"; };
 "@ledgerhq/hw-transport-node-hid-noevents@npm:6.30.5" = { filename = "@ledgerhq-hw-transport-node-hid-noevents-npm-6.30.5-19d7e6c1d0-013d7d6745.zip"; sha512 = "013d7d674573b838b3e2d6a750a8e48a1f1722d986c272513de28f68c5a203576e2b39beea1f0ea7ca5e348421b50f79d8af1a30774068479b1fa6526662eae1"; };

yarn.lock

@@ -3391,6 +3391,7 @@ __metadata:
     "@cardano-sdk/crypto": "workspace:~"
     "@cardano-sdk/util": "workspace:~"
     "@cardano-sdk/util-dev": "workspace:~"
+    "@koralabs/handles-public-api-interfaces": ^2.13.0
     "@types/lodash": ^4.14.182
     "@types/node-fetch": ^2.6.12
     "@types/validator": ^13.7.1
@@ -5173,6 +5174,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@koralabs/handles-public-api-interfaces@npm:^2.13.0":
+  version: 2.13.0
+  resolution: "@koralabs/handles-public-api-interfaces@npm:2.13.0"
+  checksum: b28895a70ecdb1b4643953dd0af11b406970a5388b79889050f19ef01335c7da29fb8696d26e80f645fd435ca8cc90f13b5fed0c4a5ceb0ac0d2447aad5e3e06
+  languageName: node
+  linkType: hard
+
 "@ledgerhq/devices@npm:^8.4.4":
   version: 8.4.4
   resolution: "@ledgerhq/devices@npm:8.4.4"