New apis and readme

Author: andreespirela

README.md

@@ -369,6 +369,128 @@ fetchRandomArtworkWithUser().then((result) => {
 })
 ```
 
+### Fetching random communities without full metadata
+
+**Signature**:  
+`fetchRandomCommunities = async (): Promise<TokenMetadataLookUp>`
+
+**Usage**:
+```typescript
+import { fetchRandomCommunities } from 'verto-cache-interface';
+
+fetchRandomCommunities().then((result) => {
+    const communities = result.entities;
+    communities.forEach((com) => {
+        console.log(com.contractId);
+        console.log(com.type);
+        console.log(com.lister);
+        console.log(com.id);
+    })
+})
+```
+
+### Fetching random communities with full metadata
+
+**Signature**:  
+`fetchRandomCommunitiesWithMetadata = async (): Promise<Array<RandomCommunities>>`
+
+**Usage**:
+```typescript
+import { fetchRandomCommunitiesWithMetadata } from 'verto-cache-interface';
+
+fetchRandomCommunitiesWithMetadata().then((result) => {
+    result.forEach((com) => {
+        console.log(com.id);
+        console.log(com.name);
+        console.log(com.ticker);
+        console.log(com.logo);
+        console.log(com.description);
+    })
+})
+```
+
+### Fetching top communities with full metadata
+
+**Signature**:  
+`fetchTopCommunities = async (): Promise<Array<RandomCommunities>>`
+
+**Usage**:
+```typescript
+import { fetchTopCommunities } from 'verto-cache-interface';
+
+fetchTopCommunities().then((result) => {
+    result.forEach((com) => {
+        console.log(com.id);
+        console.log(com.name);
+        console.log(com.ticker);
+        console.log(com.logo);
+        console.log(com.description);
+    })
+})
+```
+
+### Fetching full metadata for given communities
+
+**Signature**:  
+`fetchCommunitiesMetadata = async (communityContractIds: Array<string> | string): Promise<Array<RandomCommunities>>`
+
+**Usage**:
+```typescript
+import { fetchCommunitiesMetadata } from 'verto-cache-interface';
+
+fetchCommunitiesMetadata(["MY-community-id1", "MY-community-id2"]).then((result) => {
+    result.forEach((com) => {
+        console.log(com.id);
+        console.log(com.name);
+        console.log(com.ticker);
+        console.log(com.logo);
+        console.log(com.description);
+    })
+})
+```
+
+### Fetching artwork metadata
+
+**Signature**:  
+`fetchArtworkMetadata = async (): Promise<ArtworkMetadata | undefined>`
+
+**Usage**:
+```typescript
+import { fetchArtworkMetadata } from 'verto-cache-interface';
+
+fetchArtworkMetadata().then((result) => {
+    console.log(result.id);
+    console.log(result.name);
+    console.log(result.lister); // Object (username, name, addresses, bio, links, image)
+    console.log(result.lister.addresses);
+    console.log(result.lister.bio);
+    console.log(result.lister.links);
+})
+```
+
+### Fetching token by id and optional filtering
+
+**Signature**:  
+`fetchTokenById = async (tokenId: string, filter?: (val: CommunityContractToken) => boolean): Promise<CommunityContractToken | undefined>`
+
+**Usage**:
+```typescript
+import { fetchTokenById } from 'verto-cache-interface';
+
+fetchTokenById("ABC").then((result) => {
+    console.log(result.id);
+    console.log(result.type);
+    console.log(result.lister);
+});
+
+
+fetchTokenById("ABC", (filterData) => filterData.type === "community").then((result) => {
+    console.log(result.id);
+    console.log(result.type);
+    console.log(result.lister);
+});
+```
+
 ## Hooks
 Hooks are a way to invoke functions and then invoke certain behaviors inside the cache system.
 

src/calls/fetch-communities-metadata.ts

@@ -0,0 +1,11 @@
+import {fetchCommunityMetadata} from "./fetch-random-communities-with-metadata";
+
+/**
+ * Fetches the metadata for one (string) or more (array) communities.
+ * This returns an array with (id, name, ticker, logo, description)
+ * @param communityContractIds Single string or array of string containing the ids of the community as listed in the community contract
+ */
+export const fetchCommunitiesMetadata = async (communityContractIds: Array<string> | string) => {
+    const contractIds = Array.isArray(communityContractIds) ? [...communityContractIds] : [communityContractIds];
+    return (await fetchCommunityMetadata(contractIds));
+}

src/calls/fetch-random-communities-with-metadata.ts

@@ -14,23 +14,27 @@ export const fetchRandomCommunitiesWithMetadata = async (limit?: number): Promis
         return [];
     } else {
         const contractIds = lookupEntities.map((item) => item.contractId);
-        const communities: Array<RandomCommunities> = [];
-        for (const communitiesKey of contractIds) {
-            const contract = await fetchContract(communitiesKey, false, true);
-            if(contract) {
-                const contractState = contract.state;
-                const settings: Array<string> = (contractState.settings || []).flat();
-                const logoIndex = settings.findIndex(item => item === "communityLogo");
-                const descriptionIndex = settings.findIndex(item => item === "communityDescription");
-                communities.push({
-                    id: communitiesKey,
-                    name: contractState.name,
-                    ticker: contractState.ticker,
-                    logo: settings[logoIndex + 1],
-                    description:  settings[descriptionIndex + 1],
-                })
-            }
+        return fetchCommunityMetadata(contractIds);
+    }
+}
+
+export const fetchCommunityMetadata = async (contractIds: Array<string>) => {
+    const communities: Array<RandomCommunities> = [];
+    for (const communitiesKey of contractIds) {
+        const contract = await fetchContract(communitiesKey, false, true);
+        if(contract) {
+            const contractState = contract.state;
+            const settings: Array<string> = (contractState.settings || []).flat();
+            const logoIndex = settings.findIndex(item => item === "communityLogo");
+            const descriptionIndex = settings.findIndex(item => item === "communityDescription");
+            communities.push({
+                id: communitiesKey,
+                name: contractState.name,
+                ticker: contractState.ticker,
+                logo: settings[logoIndex + 1],
+                description:  settings[descriptionIndex + 1],
+            })
         }
-        return communities;
     }
+    return communities;
 }

src/calls/fetch-top-communities.ts

@@ -0,0 +1,16 @@
+import {fetchTokens} from "./fetch-tokens";
+import {cacheApiBaseRequest} from "./cache-api-base-request";
+import {CommunityBalancesRaw} from "./types/community-contract-state";
+import {LookUp} from "./types/lookup";
+import {fetchCommunityMetadata} from "./fetch-random-communities-with-metadata";
+
+/**
+ * Fetches the communities with the top balance amount per contract.
+ * Returns metadata containing: (id, name, ticker, logo, description)
+ * @param limit: Max to fetch
+ */
+export const fetchTopCommunities = async (limit?: number) => {
+    const cacheRequest = (await (cacheApiBaseRequest<LookUp<CommunityBalancesRaw>>(`token/communities/top?limit=${limit || 4}`)))?.data?.entities || [];
+    const contractIds = cacheRequest.map((item) => item.contractId);
+    return (await fetchCommunityMetadata(contractIds));
+}

src/calls/types/community-contract-state.ts

@@ -27,3 +27,8 @@ export interface RandomCommunities {
     logo: string;
     description: string;
 }
+
+export interface CommunityBalancesRaw {
+    contractId: string;
+    balanceLength: number;
+}

src/calls/types/lookup.ts

@@ -0,0 +1,6 @@
+import {TokenMetadata} from "./token-metadata";
+
+export interface LookUp<T = any> {
+    entities: Array<T>;
+    resultsStatus: string;
+}

src/calls/types/token-metadata.ts

@@ -1,11 +1,11 @@
+import {LookUp} from "./lookup";
+
 export interface TokenMetadata {
     contractId: string;
     type: string;
     lister: string;
     id?: string;
 }
 
-export interface TokenMetadataLookUp {
-    entities: Array<TokenMetadata>;
-    resultsStatus: string;
+export interface TokenMetadataLookUp extends LookUp<TokenMetadata> {
 }

src/index.ts

@@ -23,4 +23,10 @@ export * from './calls/fetch-users';
 export * from './calls/fetch-balance-by-username';
 export * from './calls/fetch-user-by-username';
 export * from './calls/fetch-random-artwork-with-user';
+export * from './calls/fetch-random-communities';
+export * from './calls/fetch-random-communities-with-metadata';
+export * from './calls/fetch-top-communities';
+export * from './calls/fetch-communities-metadata';
+export * from './calls/fetch-artwork-metadata';
+export * from './calls/fetch-token-by-id';
 export * from './hooks/cache-contract-hook';

src/tests/api.test.ts

@@ -15,6 +15,7 @@ import {fetchBalancesByUsername} from "../calls/fetch-balance-by-username";
 import {fetchRandomArtworkWithUser} from "../calls/fetch-random-artwork-with-user";
 import {fetchArtworkMetadata} from "../calls/fetch-artwork-metadata";
 import {fetchRandomCommunitiesWithMetadata} from "../calls/fetch-random-communities-with-metadata";
+import {fetchTopCommunities} from "../calls/fetch-top-communities";
 
 describe("API test", () => {
     test("Fetch Contract", async () => {
@@ -159,7 +160,14 @@ describe("API test", () => {
         expect(communities[0].id).not.toBeUndefined();
         expect(communities[0].name).not.toBeUndefined();
         expect(communities[0].ticker).not.toBeUndefined();
+    })
 
+    test("Fetch top communities", async () => {
+        const topComs = await fetchTopCommunities();
+        expect(topComs.length).toBeGreaterThanOrEqual(4);
+        expect(topComs[0].id).not.toBeUndefined();
+        expect(topComs[0].name).not.toBeUndefined();
+        expect(topComs[0].ticker).not.toBeUndefined();
     })
 });