Update README, add addressAssets helper

* Refactor other helpers
* Update examples

Author: everdimension

README.md

@@ -23,6 +23,71 @@ import { client } from "defi-sdk";
 client.configure({ url: endpoint, apiToken: API_TOKEN });
 ```
 
+## API
+
+### General usage
+
+### client.subscribe(options)
+
+```js
+import { client } from "defi-sdk";
+
+client.subscribe({
+  namespace: "assets",
+  body: {
+    scope: ["prices"],
+    payload: { asset_codes: ["eth"], currency: "usd" }
+  },
+  onMessage: (event: Event, data: Response) => {
+    /* handle data */
+  }
+});
+```
+
+- `namespace`: a [`Namespace`](https://docs.zerion.io/websockets/namespaces) string
+- `event`: one of `received | changed | appended | removed`, see [Zerion Docs](https://docs.zerion.io/websockets/websocket-api-overview)
+- `body`: a [`Request`](#Request) object
+- `data`: a [`Response`](#Response) object
+
+## Domain Helpers
+
+Instead of calling `client.subscribe` and passing type information manually, the SDK provides helpers for most of the existing request [scopes](https://docs.zerion.io/websockets/websocket-api-overview#request)
+
+### `addressAssets`
+
+```js
+import { client } from "defi-sdk";
+
+client.addressAssets({
+  payload: { asset_codes: ["eth"], currency: "usd" },
+  onData: data => {
+    /* handle data */
+  }
+});
+```
+
+## Types
+
+### Request
+
+```ts
+interface Request<T, ScopeName extends string> {
+  scope: ScopeName[];
+  payload: T;
+}
+```
+
+### Response
+
+```ts
+interface Response<T> {
+  meta: any;
+  payload: T;
+}
+```
+
+See `Response` in [Zerion Docs](https://docs.zerion.io/websockets/websocket-api-overview#response)
+
 ## License
 
 MIT License, see the included [LICENSE](LICENSE) file.

examples/Helpers.tsx

@@ -5,7 +5,7 @@ import { useAddressLoans } from "../src/react";
 import { EntryInfo } from "./EntryInfo";
 import { VStack } from "./VStack";
 import { TEST_ADDRESS } from "./config";
-import { client } from "../src";
+import { client, useAddressAssets } from "../src";
 
 const USDC = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
 const UNI = "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984";
@@ -156,6 +156,35 @@ export function Helpers({
           return <VStack gap={4}>full info: {entity.title}</VStack>;
         }}
       />
+      <EntryInfo
+        title="useAddressAssets"
+        entry={useAddressAssets({
+          payload: useMemo(
+            () => ({
+              currency,
+              address: TEST_ADDRESS,
+            }),
+            [currency]
+          ),
+        })}
+        render={entry => {
+          if (!entry.data) {
+            return null;
+          }
+          const { assets } = entry.data;
+          if (!assets) {
+            return <span>Entity not found</span>;
+          }
+          return Object.values(assets)
+            .slice(0, 5)
+            .map(addressAsset => (
+              <div key={addressAsset.asset.asset_code}>
+                {addressAsset.asset.name}{' '}
+                {addressAsset.quantity}
+              </div>
+            ));
+        }}
+      />
       <ImperativeAssetsPrices currency={currency} />
     </VStack>
   );

src/client.ts

@@ -18,6 +18,8 @@ import { createSocketNamespace } from "./socket/createSocketNamespace";
 import { assetsPrices } from "./domains/assetsPrices";
 import { assetsInfo } from "./domains/assetsInfo";
 import { addressLoans } from "./domains/addressLoans";
+import { addressAssets } from "./domains/addressAssets";
+import { assetsFullInfo } from "./domains/assetsFullInfo";
 
 const subsciptionEvents: SubscriptionEvent[] = [
   "received",
@@ -337,9 +339,11 @@ export class BareClient {
 }
 
 export class Client extends BareClient {
+  addressAssets = addressAssets;
+  addressLoans = addressLoans;
   assetsPrices = assetsPrices;
+  assetsFullInfo = assetsFullInfo;
   assetsInfo = assetsInfo;
-  addressLoans = addressLoans;
 }
 
 export const client = new Client(null);

src/domains/addressAssets.ts

@@ -0,0 +1,26 @@
+import type { AddressAsset } from "../entities/AddressAsset";
+import type { AddressParams } from "./AddressParams";
+import { createDomainRequest } from "./createDomainRequest";
+
+export type RequestPayload = AddressParams & {
+  currency: string;
+  asset_codes?: string[];
+};
+
+export interface ResponseData {
+  [key: string]: AddressAsset;
+}
+export const namespace = "address";
+export const scope = "assets";
+export const getId = (item: AddressAsset): string => item.asset.asset_code;
+
+export const addressAssets = createDomainRequest<
+  RequestPayload,
+  ResponseData,
+  typeof namespace,
+  typeof scope
+>({
+  namespace,
+  scope,
+  getId,
+});

src/domains/addressLoans.ts

@@ -8,13 +8,17 @@ export type RequestPayload = AddressParams & {
 };
 export type ResponseData = Loan[];
 
+export const namespace = "address";
+export const scope = "loans";
+export const mergeStrategy = mergeList;
+
 export const addressLoans = createDomainRequest<
   RequestPayload,
   ResponseData,
-  "address",
-  "loans"
+  typeof namespace,
+  typeof scope
 >({
-  namespace: "address",
-  scopeName: "loans",
-  mergeStrategy: mergeList,
+  namespace,
+  scope,
+  mergeStrategy,
 });

src/domains/assetsFullInfo.ts

@@ -9,13 +9,17 @@ export interface RequestPayload {
 
 export type ResponseData = null | AssetFullInfo;
 
+export const namespace = "assets";
+export const scope = "full-info";
+export const mergeStrategy = mergeSingleEntity;
+
 export const assetsFullInfo = createDomainRequest<
   RequestPayload,
   ResponseData,
-  "assets",
-  "full-info"
+  typeof namespace,
+  typeof scope
 >({
-  namespace: "assets",
-  scopeName: "full-info",
-  mergeStrategy: mergeSingleEntity,
+  namespace,
+  scope,
+  mergeStrategy,
 });

src/domains/assetsInfo.ts

@@ -14,14 +14,19 @@ export interface RequestPayload {
 
 export type ResponseData = AssetInfo[];
 
+export const namespace = "assets";
+export const scope = "info";
+export const getId = (item: AssetInfo): string => item.asset.asset_code;
+export const mergeStrategy = mergeList;
+
 export const assetsInfo = createDomainRequest<
   RequestPayload,
   ResponseData,
-  "assets",
-  "info"
+  typeof namespace,
+  typeof scope
 >({
-  namespace: "assets",
-  scopeName: "info",
-  getId: (item: AssetInfo) => item.asset.asset_code,
-  mergeStrategy: mergeList,
+  namespace,
+  scope,
+  getId,
+  mergeStrategy,
 });

src/domains/assetsPrices.ts

@@ -10,13 +10,17 @@ export interface ResponseData {
   [key: string]: Asset;
 }
 
+export const namespace = "assets";
+export const scope = "prices";
+export const getId = (item: Asset): string => item.asset_code;
+
 export const assetsPrices = createDomainRequest<
   RequestPayload,
   ResponseData,
-  "assets",
-  "prices"
+  typeof namespace,
+  typeof scope
 >({
-  namespace: "assets",
-  scopeName: "prices",
-  getId: (item: Asset) => item.asset_code,
+  namespace,
+  scope,
+  getId,
 });

src/domains/createDomainRequest.ts

@@ -25,12 +25,12 @@ export function createDomainRequest<
   ScopeName extends string
 >({
   namespace,
-  scopeName,
+  scope,
   getId,
   mergeStrategy,
 }: {
   namespace: Namespace;
-  scopeName: ScopeName;
+  scope: ScopeName;
   getId?: (x: any) => string | number;
   mergeStrategy?: MergeStrategy;
   client?: Client;
@@ -64,7 +64,7 @@ export function createDomainRequest<
       getId: getId || options.getId,
       mergeStrategy: mergeStrategy || options.mergeStrategy,
       body: {
-        scope: [scopeName],
+        scope: [scope],
         payload,
       },
     });

src/entities/AddressAsset.ts

@@ -0,0 +1,6 @@
+import type { Asset } from "./Asset";
+
+export interface AddressAsset {
+  asset: Asset;
+  quantity: string;
+}

src/index.ts

@@ -9,8 +9,17 @@ export type { CachePolicy } from "./cache/CachePolicy";
 export type { Entry } from "./cache/Entry";
 export { DataStatus } from "./cache/DataStatus";
 
+// domain helpers
+export { addressLoans } from "./domains/addressLoans";
+export { addressAssets } from "./domains/addressAssets";
+export { assetsFullInfo } from "./domains/assetsFullInfo";
+export { assetsInfo } from "./domains/assetsInfo";
+export { assetsPrices } from "./domains/assetsPrices";
+
 // react bindings
 export { useSubscription } from "./react/useSubscription";
+export { useAddressAssets } from "./react/domains/useAddressAssets";
 export { useAddressLoans } from "./react/domains/useAddressLoans";
+export { useAssetsFullInfo } from "./react/domains/useAssetsFullInfo";
 export { useAssetsInfo } from "./react/domains/useAssetsInfo";
 export { useAssetsPrices } from "./react/domains/useAssetsPrices";

src/react/domains/createDomainHook.ts

@@ -19,12 +19,12 @@ export function createDomainHook<
   ScopeName extends string
 >({
   namespace,
-  scopeName,
+  scope,
   getId,
   mergeStrategy,
 }: {
   namespace: Namespace;
-  scopeName: ScopeName;
+  scope: ScopeName;
   getId?: (x: any) => string | number;
   mergeStrategy?: MergeStrategy;
 }) {
@@ -41,7 +41,7 @@ export function createDomainHook<
       mergeStrategy: mergeStrategy || options.mergeStrategy,
       body: useMemo(
         () => ({
-          scope: [scopeName],
+          scope: [scope],
           payload,
         }),
         [payload]

src/react/domains/useAddressAssets.ts

@@ -0,0 +1,14 @@
+import type { RequestPayload, ResponseData } from "../../domains/addressAssets";
+import { namespace, scope, getId } from "../../domains/addressAssets";
+import { createDomainHook } from "./createDomainHook";
+
+export const useAddressAssets = createDomainHook<
+  RequestPayload,
+  ResponseData,
+  typeof namespace,
+  typeof scope
+>({
+  namespace,
+  scope,
+  getId,
+});

src/react/domains/useAddressLoans.ts

@@ -1,14 +1,14 @@
-import { RequestPayload, ResponseData } from "../../domains/addressLoans";
-import { mergeList } from "../../shared/mergeStrategies";
+import type { RequestPayload, ResponseData } from "../../domains/addressLoans";
+import { namespace, scope, mergeStrategy } from "../../domains/addressLoans";
 import { createDomainHook } from "./createDomainHook";
 
 export const useAddressLoans = createDomainHook<
   RequestPayload,
   ResponseData,
-  "address",
-  "loans"
+  typeof namespace,
+  typeof scope
 >({
-  namespace: "address",
-  scopeName: "loans",
-  mergeStrategy: mergeList,
+  namespace,
+  scope,
+  mergeStrategy,
 });

src/react/domains/useAssetsFullInfo.ts

@@ -2,16 +2,16 @@ import type {
   RequestPayload,
   ResponseData,
 } from "../../domains/assetsFullInfo";
-import { mergeSingleEntity } from "../../shared/mergeStrategies";
+import { namespace, scope, mergeStrategy } from "../../domains/assetsFullInfo";
 import { createDomainHook } from "./createDomainHook";
 
 export const useAssetsFullInfo = createDomainHook<
   RequestPayload,
-  ResponseData | null,
-  "assets",
-  "full-info"
+  ResponseData,
+  typeof namespace,
+  typeof scope
 >({
-  namespace: "assets",
-  scopeName: "full-info",
-  mergeStrategy: mergeSingleEntity,
+  namespace,
+  scope,
+  mergeStrategy,
 });