@decafhub/decaf-client-extras 0.4.0 → 0.5.1

package/src/{index.test.ts → reports/index.test.ts}

@@ -2,12 +2,16 @@ import { buildDecafClient, DecafClient, gql } from '@decafhub/decaf-client';
 import { safeDiv, zero } from '@telostat/prelude';
 import { fail } from 'assert';
 import dayjs from 'dayjs';
-import { DecafPortfolioId, mkCurrencyCodeError } from './commons';
-import { makeValuationReportHoldingsTree } from './reports/valuation/';
+import { DecafAccountId, DecafPortfolioId, mkCurrencyCodeError } from '../commons';
+import { makeValuationReportHoldingsTree } from './valuation';
 import {
   fetchPortfolioValuationReport,
   fetchRemotePortfolioValuationReport,
-} from './reports/valuation/-remote-valuation-report-portfolio';
+} from './valuation/-remote-valuation-report-portfolio';
+import {
+  fetchAccountValuationReport,
+  fetchRemoteAccountValuationReport,
+} from './valuation/-remote-valuation-report-account';
 
 const API_URL = process.env.TESTING_API_URL;
 const API_KEY = process.env.TESTING_API_KEY;
@@ -22,9 +26,19 @@ const FIRST_PORTFOLIO_QUERY = gql`
   }
 `;
 
-describe('Main', () => {
+const FIRST_ACCOUNT_QUERY = gql`
+  query GetFirstAccount {
+    account(limit: 1) {
+      id
+      name
+    }
+  }
+`;
+
+describe('Reports', () => {
   let client: DecafClient;
   let portfolioId: DecafPortfolioId;
+  let accountId: DecafAccountId;
 
   beforeAll(() => {
     jest.resetModules();
@@ -52,6 +66,16 @@ describe('Main', () => {
     }
   });
 
+  test('take the first account', async () => {
+    try {
+      const { data } = await client.microlot.query({ query: FIRST_ACCOUNT_QUERY });
+      accountId = data?.account?.[0].id;
+      expect(accountId).toBeDefined();
+    } catch (e) {
+      fail('Error while fetching the first account');
+    }
+  });
+
   test('get a remote portfolio report successfuly', async () => {
     const eValue = await fetchRemotePortfolioValuationReport(client, {
       portfolio: portfolioId,
@@ -66,6 +90,7 @@ describe('Main', () => {
           `Success! remote valuation for portfolio ID ${value.portfolio.id} is reported at ${value.reported}`
         );
         expect(value).toBeDefined();
+        expect(value.portfolio.id).toEqual(portfolioId);
       },
     });
   });
@@ -94,4 +119,45 @@ describe('Main', () => {
       },
     });
   });
+
+  test('get a remote account report successfuly', async () => {
+    const eValue = await fetchRemoteAccountValuationReport(client, {
+      account: accountId,
+      date: dayjs(new Date()).format('YYYY-MM-DD'),
+      dateType: 'settlement',
+      currency: mkCurrencyCodeError('EUR'),
+    });
+    eValue.caseOf({
+      Left: (e) => fail('Error while fetching the remote account report: ' + e.msg),
+      Right: (value) => {
+        console.log(`Success! remote valuation for account ID ${value.account.id} is reported at ${value.reported}`);
+        expect(value).toBeDefined();
+        expect(value.account.id).toEqual(accountId);
+      },
+    });
+  });
+
+  test('get an account report, check the tree', async () => {
+    const eValue = await fetchAccountValuationReport(client, {
+      account: accountId,
+      date: dayjs(new Date()).format('YYYY-MM-DD'),
+      dateType: 'settlement',
+      currency: mkCurrencyCodeError('EUR'),
+    });
+    eValue.caseOf({
+      Left: (e) => fail('Error while fetching the remote account report: ' + String(e)),
+      Right: (value) => {
+        console.log(`Success! remote valuation for account ID ${value.account.id} is reported at ${value.asof}`);
+
+        expect(value).toBeDefined();
+
+        const nav = value.figures.nav;
+        const inv = value.figures.investment;
+        const holdings = value.holdings;
+        const tree = makeValuationReportHoldingsTree(nav, inv, holdings, 'country');
+        expect(tree).toBeDefined();
+        expect(safeDiv(tree.totals.netExposure, nav).orDefault(zero)).toEqual(tree.totals.netExposureRatio);
+      },
+    });
+  });
 });

package/src/reports/valuation/-remote-valuation-report-account.ts

@@ -0,0 +1,297 @@
+import { DecafClient } from '@decafhub/decaf-client';
+import {
+  CustomError,
+  customError,
+  decimalFromNullable,
+  Either,
+  Left,
+  Maybe,
+  Right,
+  sanitizedNonEmptyText,
+  SDate,
+  SDateTime,
+  unsafeDecimal,
+  zero,
+} from '@telostat/prelude';
+import {
+  CurrencyCode,
+  DateType,
+  DecafAccountId,
+  DecafActionId,
+  DecafExternalValuationId,
+  DecafOhlcSeriesId,
+  DecafPortfolioId,
+  DecafPrincipalId,
+  DecafShareClassFeeScheduleId,
+  DecafShareClassId,
+} from '../../commons';
+import { recompileBaseValuationReport, RemoteBaseValuationReport } from './-remote-valuation-report-shared';
+import { ValuationReportAccount } from './-valuation-report-shared';
+import { AccountValuationReport, AccountValuationReportShareClassValue } from './-valuation-report-account';
+
+/**
+ * Remote account valuation report query type.
+ */
+export interface AccountValuationReportQuery {
+  /**
+   * Date of valuation report.
+   */
+  date: SDate;
+
+  /**
+   * Date type of the valuation report.
+   */
+  dateType: DateType;
+
+  /**
+   * Reference currency of the valuation report.
+   */
+  currency: CurrencyCode;
+
+  /**
+   * Account the valuation report is requested for.
+   */
+  account: DecafAccountId;
+}
+
+/**
+ * Type definition for the remote (raw) account valuation report data.
+ */
+export interface RemoteAccountValuationReport extends RemoteBaseValuationReport {
+  account: ValuationReportAccount;
+  scvals: RemoteValuationShareClassValue[];
+  subscriptions?: number;
+}
+
+/**
+ * Type definition for share class valuation on the remote account valuation
+ * report.
+ */
+export interface RemoteValuationShareClassValue {
+  shareclass?: RemoteValuationShareClass;
+  external?: RemoteValuationExternalValue;
+  nav: number;
+  nav_adjusted: number;
+  nav_adjusted_total: number;
+  coefficient: number;
+  gav_refccy: number;
+  gav_clsccy: number;
+  sharecount_prev: number;
+  sharecount_curr: number;
+  sharecount_diff: number;
+  px_refccy: number;
+  px_clsccy: number;
+  ytdext?: number;
+  ytdint?: number;
+}
+
+/**
+ * Type definition for share class on the remote account valuation report.
+ */
+export interface RemoteValuationShareClass {
+  id: DecafShareClassId;
+  created: SDateTime;
+  creator: DecafPrincipalId;
+  updated: SDateTime;
+  updater: DecafPrincipalId;
+  guid: string;
+  portfolio: DecafPortfolioId;
+  name: string;
+  currency: CurrencyCode;
+  isin?: string;
+  bbgticker?: string;
+  liquidity?: string;
+  jurisdiction?: string;
+  administrator?: string;
+  mininvestment?: number;
+  subredperiod?: string;
+  freqmngt?: number;
+  freqperf?: number;
+  benchmark?: DecafOhlcSeriesId;
+  description?: string;
+  feeschedules: DecafShareClassFeeScheduleId[];
+  effectivefeeschedule?: DecafShareClassFeeScheduleId;
+  subscriptions: DecafActionId[];
+  outstanding?: number;
+}
+
+/**
+ * Type definition for external valuation on the remote account valuation
+ * report.
+ */
+export interface RemoteValuationExternalValue {
+  id: DecafExternalValuationId;
+  created: SDateTime;
+  creator: DecafPrincipalId;
+  updated: SDateTime;
+  updater: DecafPrincipalId;
+  guid: string;
+  portfolio: DecafPortfolioId;
+  shareclass?: DecafShareClassId;
+  date: SDate;
+  ccy: CurrencyCode;
+  shares?: number;
+  price?: number;
+  nav?: number;
+  aum?: number;
+  hedgepnl?: number;
+  feemngt?: number;
+  feeperf?: number;
+  otheraccrued?: number;
+  totalaccrued?: number;
+  subred?: number;
+  perfdaily?: number;
+  perfweekly?: number;
+  perfmonthly?: number;
+  perfytd?: number;
+  perfstart?: number;
+  coefficient?: number;
+}
+
+/**
+ * Attempts to retrieve remote account valuation report.
+ *
+ * @param client DECAF Barista client.
+ * @param query Remote account valuation report endpoint query parameters.
+ * @returns Remote (raw) account valuation report data.
+ */
+export async function fetchRemoteAccountValuationReport(
+  client: DecafClient,
+  query: AccountValuationReportQuery
+): Promise<Either<CustomError, RemoteAccountValuationReport>> {
+  return client.barista
+    .get<RemoteAccountValuationReport>('/reports/valuation/account/', {
+      params: {
+        ccy: query.currency,
+        date: query.date,
+        type: query.dateType,
+        account: `${query.account}`,
+      },
+    })
+    .then((x) => Right(x.data))
+    .catch((err) => Left(customError('Error while attempting to fetch remote account valuation report', err)));
+}
+
+/**
+ * Attempts to recompile remote valuation report share class value.
+ *
+ * @param x remote valuation report share class value object.
+ * @return Recompiled valuation report share class value object.
+ */
+export function toShareClassValue(s: RemoteValuationShareClassValue): AccountValuationReportShareClassValue {
+  const shareclass = Maybe.fromNullable(s.shareclass).map((x) => ({
+    id: x.id,
+    created: x.created,
+    creator: Maybe.fromNullable(x.creator),
+    updated: x.updated,
+    updater: Maybe.fromNullable(x.updater),
+    guid: x.guid,
+    portfolio: x.portfolio,
+    name: x.name,
+    currency: x.currency,
+    isin: sanitizedNonEmptyText(x.isin),
+    bbgticker: sanitizedNonEmptyText(x.bbgticker),
+    liquidity: sanitizedNonEmptyText(x.liquidity),
+    jurisdiction: sanitizedNonEmptyText(x.jurisdiction),
+    administrator: sanitizedNonEmptyText(x.administrator),
+    minimumInvestment: Maybe.fromNullable(x.mininvestment),
+    subscriptionRedemptionPeriod: sanitizedNonEmptyText(x.subredperiod),
+    managementFeeFrequency: Maybe.fromNullable(x.freqmngt),
+    performanceFeeFrequency: Maybe.fromNullable(x.freqperf),
+    benchmark: Maybe.fromNullable(x.benchmark),
+    description: sanitizedNonEmptyText(x.description),
+    feeScheduleIds: x.feeschedules,
+    effectiveFeeScheduleId: Maybe.fromNullable(x.effectivefeeschedule),
+    subscriptionIds: x.subscriptions,
+    outstanding: decimalFromNullable(x.outstanding),
+  }));
+
+  return {
+    shareclass,
+    external: Maybe.fromNullable(s.external).map((ev) => ({
+      id: ev.id,
+      created: ev.created,
+      creator: Maybe.fromNullable(ev.updater),
+      updated: ev.updated,
+      updater: Maybe.fromNullable(ev.updater),
+      guid: ev.guid,
+      portfolio: ev.portfolio,
+      shareclass: Maybe.fromNullable(ev.shareclass),
+      date: ev.date,
+      ccy: ev.ccy,
+      shares: decimalFromNullable(ev.shares),
+      price: decimalFromNullable(ev.price),
+      nav: decimalFromNullable(ev.nav),
+      aum: decimalFromNullable(ev.aum),
+      hedgepnl: decimalFromNullable(ev.hedgepnl),
+      feemngt: decimalFromNullable(ev.feemngt),
+      feeperf: decimalFromNullable(ev.feeperf),
+      otheraccrued: decimalFromNullable(ev.otheraccrued),
+      totalaccrued: decimalFromNullable(ev.totalaccrued),
+      subred: decimalFromNullable(ev.subred),
+      perfdaily: decimalFromNullable(ev.perfdaily),
+      perfweekly: decimalFromNullable(ev.perfweekly),
+      perfmonthly: decimalFromNullable(ev.perfmonthly),
+      perfytd: decimalFromNullable(ev.perfytd),
+      perfstart: decimalFromNullable(ev.perfstart),
+      coefficient: decimalFromNullable(ev.coefficient),
+    })),
+    nav: unsafeDecimal(s.nav),
+    navAdjusted: unsafeDecimal(s.nav_adjusted),
+    navAdjustedTotal: unsafeDecimal(s.nav_adjusted_total),
+    coefficient: unsafeDecimal(s.coefficient),
+    gavRefccy: unsafeDecimal(s.gav_refccy),
+    gavClsccy: unsafeDecimal(s.gav_clsccy),
+    sharecountPrev: Maybe.fromNullable(s.sharecount_prev).map(unsafeDecimal),
+    sharecountCurr: Maybe.fromNullable(s.sharecount_curr).map(unsafeDecimal),
+    sharecountDiff: Maybe.fromNullable(s.sharecount_diff).map(unsafeDecimal),
+    pxRefCcy: decimalFromNullable(s.px_refccy),
+    pxClsCcy: decimalFromNullable(s.px_clsccy),
+    ytdExt: decimalFromNullable(s.ytdext),
+    ytdInt: decimalFromNullable(s.ytdint),
+  };
+}
+
+/**
+ * Attempts to re-compile the raw, remote account valuation report and
+ * return it.
+ *
+ * @param x Raw, remote account valuation report.
+ * @returns Either of an error message or the re-compiled account valuation
+ * report.
+ */
+export function recompileAccountValuationReport(
+  x: RemoteAccountValuationReport
+): Either<CustomError, AccountValuationReport> {
+  // Attempt to get the base valuation report:
+  const baseReport = recompileBaseValuationReport(x);
+
+  // Add consolidated valuation report specific fields and return:
+  return baseReport.map((report) => {
+    return {
+      ...report,
+      account: x.account,
+      subscriptions: decimalFromNullable(x.subscriptions).orDefault(zero),
+      shareClassValues: x.scvals.map(toShareClassValue),
+    };
+  });
+}
+
+/**
+ * Attempts to retrieve remote account valuation report, compiles it to
+ * {@link AccountValuationReport} and return it.
+ *
+ * @param client DECAF Barista client.
+ * @param query Remote account valuation report endpoint query parameters.
+ * @returns Recompiled account valuation report data.
+ */
+export async function fetchAccountValuationReport(
+  client: DecafClient,
+  query: AccountValuationReportQuery
+): Promise<Either<CustomError, AccountValuationReport>> {
+  // Attempt to fetch the remote, raw report:
+  const rawReport = await fetchRemoteAccountValuationReport(client, query);
+
+  // Attempt to recompile the report (if any) and return:
+  return rawReport.chain(recompileAccountValuationReport);
+}

package/src/reports/valuation/-valuation-report-account.ts

@@ -0,0 +1,92 @@
+import { Decimal, Maybe, SDate, SDateTime } from '@telostat/prelude';
+import {
+  DecafActionId,
+  CurrencyCode,
+  DecafExternalValuationId,
+  DecafOhlcSeriesId,
+  DecafPortfolioId,
+  DecafPrincipalId,
+  DecafShareClassFeeScheduleId,
+  DecafShareClassId,
+} from '../../commons';
+import { BaseValuationReport, ValuationReportAccount } from './-valuation-report-shared';
+
+export interface AccountValuationReport extends BaseValuationReport {
+  account: ValuationReportAccount;
+  subscriptions: Decimal;
+  shareClassValues: AccountValuationReportShareClassValue[];
+}
+
+export interface AccountValuationReportShareClassValue {
+  shareclass: Maybe<AccountValuationReportShareClass>;
+  external: Maybe<AccountValuationReportExternalValue>;
+  nav: Decimal;
+  navAdjusted: Decimal;
+  navAdjustedTotal: Decimal;
+  coefficient: Decimal;
+  gavRefccy: Decimal;
+  gavClsccy: Decimal;
+  sharecountPrev: Maybe<Decimal>;
+  sharecountCurr: Maybe<Decimal>;
+  sharecountDiff: Maybe<Decimal>;
+  pxRefCcy: Maybe<Decimal>;
+  pxClsCcy: Maybe<Decimal>;
+  ytdExt: Maybe<Decimal>;
+  ytdInt: Maybe<Decimal>;
+}
+
+export interface AccountValuationReportShareClass {
+  id: DecafShareClassId;
+  created: SDateTime;
+  creator: Maybe<DecafPrincipalId>;
+  updated: SDateTime;
+  updater: Maybe<DecafPrincipalId>;
+  guid: string;
+  portfolio: DecafPortfolioId;
+  name: string;
+  currency: CurrencyCode;
+  isin: Maybe<string>;
+  bbgticker: Maybe<string>;
+  liquidity: Maybe<string>;
+  jurisdiction: Maybe<string>;
+  administrator: Maybe<string>;
+  minimumInvestment: Maybe<number>;
+  subscriptionRedemptionPeriod: Maybe<string>;
+  managementFeeFrequency: Maybe<number>;
+  performanceFeeFrequency: Maybe<number>;
+  benchmark: Maybe<DecafOhlcSeriesId>;
+  description: Maybe<string>;
+  feeScheduleIds: DecafShareClassFeeScheduleId[];
+  effectiveFeeScheduleId: Maybe<DecafShareClassFeeScheduleId>;
+  subscriptionIds: DecafActionId[];
+  outstanding: Maybe<Decimal>;
+}
+
+export interface AccountValuationReportExternalValue {
+  id: DecafExternalValuationId;
+  created: SDateTime;
+  creator: Maybe<DecafPrincipalId>;
+  updated: SDateTime;
+  updater: Maybe<DecafPrincipalId>;
+  guid: string;
+  portfolio: DecafPortfolioId;
+  shareclass: Maybe<DecafShareClassId>;
+  date: SDate;
+  ccy: CurrencyCode;
+  shares: Maybe<Decimal>;
+  price: Maybe<Decimal>;
+  nav: Maybe<Decimal>;
+  aum: Maybe<Decimal>;
+  hedgepnl: Maybe<Decimal>;
+  feemngt: Maybe<Decimal>;
+  feeperf: Maybe<Decimal>;
+  otheraccrued: Maybe<Decimal>;
+  totalaccrued: Maybe<Decimal>;
+  subred: Maybe<Decimal>;
+  perfdaily: Maybe<Decimal>;
+  perfweekly: Maybe<Decimal>;
+  perfmonthly: Maybe<Decimal>;
+  perfytd: Maybe<Decimal>;
+  perfstart: Maybe<Decimal>;
+  coefficient: Maybe<Decimal>;
+}

package/src/reports/valuation/-valuation-report-holdings-tree/-machinery.ts

@@ -1,8 +1,12 @@
 import { Decimal, Just, List, Maybe, Nothing, safeDiv, sumDecimals, Tuple, zero } from '@telostat/prelude';
 import { ValuationReportHolding, ValuationReportHoldingClassification } from '../-valuation-report-shared';
 import { DecafArtifactTypeId } from '../../../commons';
-import { ValuationReportHoldingsTreeNode, ValuationReportHoldingsTreeNodeValue } from './-types';
-import { compareStringArrays } from './-utils';
+import {
+  AvailableAddresserKeys,
+  ValuationReportHoldingsTreeNode,
+  ValuationReportHoldingsTreeNodeValue,
+} from './-types';
+import { addressers, compareStringArrays } from './-utils';
 
 export function makeValuationReportHoldingsTreeNodeValue(): ValuationReportHoldingsTreeNodeValue {
   return {
@@ -161,7 +165,8 @@ export function addValuationReportHoldingToTree(
 export function makeValuationReportHoldingsTree(
   nav: Decimal,
   investment: Decimal,
-  holdings: ValuationReportHolding[]
+  holdings: ValuationReportHolding[],
+  addressKey: AvailableAddresserKeys = 'classification'
 ): ValuationReportHoldingsTreeNode {
   // Initialize the tree:
   const tree = makeValuationReportHoldingsTreeNode([]);
@@ -169,7 +174,10 @@ export function makeValuationReportHoldingsTree(
 
   // Iterate over the holdings and attempt to add to the tree:
   for (const holding of holdings) {
-    addValuationReportHoldingToTree(tree, holding.classification, holding);
+    // Get the address of the holding:
+    const address = addressers[addressKey](holding);
+
+    addValuationReportHoldingToTree(tree, address, holding);
   }
 
   // Retreat the tree:

package/src/reports/valuation/-valuation-report-holdings-tree/-types.ts

@@ -23,3 +23,13 @@ export interface ValuationReportHoldingsTreeNodeValue {
   pnl: Decimal;
   pnlRatio: Decimal;
 }
+
+// export interface HoldingAddressSegment {
+//   value: string;
+//   label: string;
+//   order: string | number;
+// }
+
+export type HoldingAddress = ValuationReportHoldingClassification; // HoldingAddressSegment[];
+export type HoldingAddresser = (holding: ValuationReportHolding) => HoldingAddress;
+export type AvailableAddresserKeys = 'classification' | 'currency' | 'country' | 'issuer' | 'sector';

package/src/reports/valuation/-valuation-report-holdings-tree/-utils.ts

@@ -1,3 +1,7 @@
+import { Maybe } from '@telostat/prelude';
+import { ValuationReportHolding } from '../-valuation-report-shared';
+import { AvailableAddresserKeys, HoldingAddress, HoldingAddresser } from './-types';
+
 export function compareStringArrays(x: string[], y: string[]): number {
   const xLen = x.length;
   const yLen = y.length;
@@ -13,3 +17,42 @@ export function compareStringArrays(x: string[], y: string[]): number {
 
   return Math.sign(xLen - yLen);
 }
+
+export function composeHoldingAddressers(addressers: Array<HoldingAddresser>): HoldingAddresser {
+  return (holding: ValuationReportHolding) =>
+    addressers.reduce((p: HoldingAddress, c: HoldingAddresser) => [...p, ...c(holding)], []);
+}
+
+export function makeSimpleAddresser(
+  def: string,
+  labeler: (holding: ValuationReportHolding) => Maybe<string>
+): HoldingAddresser {
+  return (holding: ValuationReportHolding) => {
+    // Attempt to get the label:
+    const label = labeler(holding).orDefault('') || def;
+
+    // Get the value:
+    const value = label.toUpperCase();
+
+    // Done, return:
+    return [{ name: value, order: value }];
+  };
+}
+
+export const addressers: Record<AvailableAddresserKeys, HoldingAddresser> = {
+  classification: (holding: ValuationReportHolding) => {
+    // Get the classification:
+    const classification = holding.classification;
+
+    // Build the address and return:
+    return classification.map((x) => ({
+      // label: x.name,
+      name: x.name.toUpperCase(),
+      order: `${x.order}`.toUpperCase(),
+    }));
+  },
+  currency: makeSimpleAddresser('[Undefined Currency]', (holding: ValuationReportHolding) => holding.artifact.ccy),
+  country: makeSimpleAddresser('[Undefined Country]', (holding: ValuationReportHolding) => holding.artifact.country),
+  issuer: makeSimpleAddresser('[Undefined Issuer]', (holding: ValuationReportHolding) => holding.artifact.issuer),
+  sector: makeSimpleAddresser('[Undefined Sector]', (holding: ValuationReportHolding) => holding.artifact.sector),
+};

package/src/reports/valuation/index.ts

@@ -2,7 +2,10 @@ export { fetchConsolidatedValuationReport } from './-remote-valuation-report-con
 export type { ConsolidatedValuationReportQuery } from './-remote-valuation-report-consolidated';
 export { fetchPortfolioValuationReport } from './-remote-valuation-report-portfolio';
 export type { PortfolioValuationReportQuery } from './-remote-valuation-report-portfolio';
+export { fetchAccountValuationReport } from './-remote-valuation-report-account';
+export type { AccountValuationReportQuery } from './-remote-valuation-report-account';
 export * from './-valuation-report-consolidated';
 export * from './-valuation-report-holdings-tree';
 export * from './-valuation-report-portfolio';
 export * from './-valuation-report-shared';
+export * from './-valuation-report-account';