@decafhub/decaf-client-extras 0.0.1

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

@@ -0,0 +1,313 @@
+import {
+  asDecimal,
+  CustomError,
+  Decimal,
+  Either,
+  Just,
+  Maybe,
+  maybeDecimal,
+  Right,
+  safeDiv,
+  sanitizedNonEmptyText,
+  SDate,
+  SDateTime,
+  zero,
+} from '@telostat/prelude';
+import { ArtifactId, ArtifactTypeId, CurrencyCode, DateType } from '../../commons';
+import {
+  BaseValuationReport,
+  BaseValuationReportHolding,
+  ValuationReportAccount,
+  ValuationReportAccounts,
+  ValuationReportAccrual,
+  ValuationReportArtifact,
+  ValuationReportFigureOrgRef,
+  ValuationReportHolding,
+} from './-valuation-report-shared';
+
+export interface RemoteBaseValuationReport {
+  reported: SDateTime;
+  asof: SDate;
+  type: DateType;
+  ccy: CurrencyCode;
+  accounts: ValuationReportAccounts;
+  holdings: RemoteValuationReportHolding[];
+  accruals: RemoteValuationReportAccrual[];
+  investment?: number;
+  valuation_net?: number;
+  valuation_abs?: number;
+  accrued?: number;
+  liabilities?: number;
+  gav?: number;
+  nav?: number;
+  aum?: number;
+  pnl?: number;
+  pnl_to_investment?: number;
+  fxrates: RemoteValuationReportFxRate[];
+}
+
+export interface RemoteValuationReportFxRate {
+  ccy1: CurrencyCode;
+  ccy2: CurrencyCode;
+  value: number; // TODO: Check when no such rate is defined.
+  asof: SDate;
+}
+
+/**
+ * Valuation holding.
+ */
+export interface RemoteValuationReportHolding {
+  artifact: RemoteValuationReportArtifact;
+  tags: { classification: { name: string; order?: string | number }[] };
+  quantity: number;
+  accounts: ValuationReportAccount[];
+  investment: {
+    px: { org?: number; ref?: number };
+    txncosts: { org?: number; ref?: number };
+    accrued: { org?: number; ref?: number };
+    value: { org?: number; ref?: number };
+  };
+  valuation: {
+    px: { org?: number; ref?: number };
+    accrued: { org?: number; ref?: number };
+    value: {
+      net: { org?: number; ref?: number };
+      abs: { org?: number; ref?: number };
+    };
+    exposure: {
+      net: { org?: number; ref?: number };
+      abs: { org?: number; ref?: number };
+    };
+  };
+  children: RemoteValuationReportChildHolding[];
+  change?: number;
+  pnl?: number;
+  pnl_to_investment?: number;
+  opendate: SDate;
+  lastdate: SDate;
+}
+
+/**
+ * Valuation child holding.
+ */
+export interface RemoteValuationReportChildHolding {
+  artifact: RemoteValuationReportArtifact;
+  tags: {};
+  quantity: number;
+  accounts: ValuationReportAccount[];
+  investment: {
+    px: { org?: number; ref?: number };
+    txncosts: { org?: number; ref?: number };
+    accrued: { org?: number; ref?: number };
+    value: { org?: number; ref?: number };
+  };
+  valuation: {
+    px: { org?: number; ref?: number };
+    accrued: { org?: number; ref?: number };
+    value: {
+      net: { org?: number; ref?: number };
+      abs: { org?: number; ref?: number };
+    };
+    exposure: {
+      net: { org?: number; ref?: number };
+      abs: { org?: number; ref?: number };
+    };
+  };
+  change?: number;
+  pnl?: number;
+  pnl_to_investment?: number;
+  opendate: SDate;
+  lastdate: SDate;
+}
+
+/**
+ * Valuation artifact.
+ */
+export interface RemoteValuationReportArtifact {
+  id: ArtifactId;
+  guid: string;
+  type: { id: ArtifactTypeId; name: string; order: number };
+  stype?: string;
+  symbol: string;
+  name?: string;
+  ccy?: CurrencyCode;
+  quantity: number;
+  country?: string;
+  issuer?: string;
+  sector?: string;
+  mic?: string;
+  ticker?: string;
+  isin?: string;
+  figi?: string;
+  expiry?: SDate;
+  underlying_id?: ArtifactId;
+}
+
+/**
+ * Valuation accrual.
+ */
+export interface RemoteValuationReportAccrual {
+  name: string;
+  value: number;
+  accounts: RemoteValuationReportAccrualByAccount[];
+}
+
+/**
+ * Valuation accrual by account.
+ */
+export interface RemoteValuationReportAccrualByAccount {
+  account: ValuationReportAccount;
+  value: number;
+  accruals: RemoteValuationReportAccrualByCurrency[];
+}
+
+/**
+ * Valuation accrual by account by currency.
+ */
+export interface RemoteValuationReportAccrualByCurrency {
+  artifact: RemoteValuationReportArtifact;
+  ccy: CurrencyCode;
+  value: { org?: number; ref?: number };
+}
+
+export function toArtifact(x: RemoteValuationReportArtifact): ValuationReportArtifact {
+  return {
+    id: x.id,
+    guid: x.guid,
+    type: x.type,
+    stype: sanitizedNonEmptyText(x.stype),
+    symbol: x.symbol,
+    name: sanitizedNonEmptyText(x.name),
+    ccy: Maybe.fromNullable(x.ccy),
+    quantity: asDecimal(x.quantity),
+    country: sanitizedNonEmptyText(x.country),
+    issuer: sanitizedNonEmptyText(x.issuer),
+    sector: sanitizedNonEmptyText(x.sector),
+    mic: sanitizedNonEmptyText(x.mic),
+    ticker: sanitizedNonEmptyText(x.ticker),
+    isin: sanitizedNonEmptyText(x.isin),
+    figi: sanitizedNonEmptyText(x.figi),
+    expiry: Maybe.fromNullable(x.expiry),
+    underlyingId: Maybe.fromNullable(x.underlying_id),
+  };
+}
+
+export function toAccrual(x: RemoteValuationReportAccrual): ValuationReportAccrual {
+  return {
+    name: x.name,
+    value: asDecimal(x.value),
+    accounts: x.accounts.map((y) => ({
+      account: y.account,
+      value: asDecimal(y.value),
+      accruals: y.accruals.map((z) => ({
+        artifact: toArtifact(z.artifact),
+        ccy: z.ccy,
+        value: { org: asDecimal(z.value.org || 0), ref: asDecimal(z.value.ref || 0) },
+      })),
+    })),
+  };
+}
+
+export function toOrgRef(x: { org?: number; ref?: number }): ValuationReportFigureOrgRef {
+  return {
+    org: maybeDecimal(x.org).orDefault(zero),
+    ref: maybeDecimal(x.ref).orDefault(zero),
+  };
+}
+
+export function toMaybeOrgRef(x?: { org?: number; ref?: number }): Maybe<ValuationReportFigureOrgRef> {
+  return Maybe.fromNullable(x).chain(({ org, ref }) =>
+    maybeDecimal(org).chain((o) => maybeDecimal(ref).chain((r) => Just({ org: o, ref: r })))
+  );
+}
+
+export function toBaseHolding(
+  nav: Decimal,
+  x: RemoteValuationReportHolding | RemoteValuationReportChildHolding
+): BaseValuationReportHolding {
+  return {
+    artifact: toArtifact(x.artifact),
+    quantity: asDecimal(x.quantity),
+    investment: {
+      px: toOrgRef(x.investment.px),
+      txncosts: toMaybeOrgRef(x.investment.txncosts),
+      accrued: toMaybeOrgRef(x.investment.accrued),
+      value: toOrgRef(x.investment.value),
+    },
+    valuation: {
+      px: toOrgRef(x.valuation.px),
+      accrued: toMaybeOrgRef(x.valuation.accrued),
+      value: {
+        net: toOrgRef(x.valuation.value.net),
+        abs: toOrgRef(x.valuation.value.abs),
+      },
+      exposure: {
+        net: toOrgRef(x.valuation.exposure.net),
+        abs: toOrgRef(x.valuation.exposure.abs),
+      },
+    },
+    valuePercentage: safeDiv(maybeDecimal(x.valuation.value.net.ref).orDefault(zero), nav),
+    netExposurePercentage: safeDiv(maybeDecimal(x.valuation.exposure.net.ref).orDefault(zero), nav),
+    absExposurePercentage: safeDiv(maybeDecimal(x.valuation.exposure.abs.ref).orDefault(zero), nav),
+    change: maybeDecimal(x.change),
+    pnl: maybeDecimal(x.pnl).orDefault(zero),
+    pnlToInvestment: maybeDecimal(x.pnl_to_investment),
+    opendate: x.opendate,
+    lastdate: x.lastdate,
+  };
+}
+
+export function toHolding(nav: Decimal, x: RemoteValuationReportHolding): ValuationReportHolding {
+  return {
+    ...toBaseHolding(nav, x),
+    classification: x.tags.classification.map((n) => ({ ...n, order: n.order || '' })),
+    accounts: x.accounts,
+    children: Maybe.fromNullable(x.children)
+      .filter((mc) => mc.length !== 0)
+      .map((mc) =>
+        mc.map((c) => ({
+          ...toBaseHolding(nav, c),
+          account: c.accounts[0] as ValuationReportAccount,
+        }))
+      ),
+  };
+}
+
+/**
+ * Attempts to re-compile the raw, remote base valuation report and
+ * return it.
+ *
+ * @param x Raw, remote base valuation report.
+ * @returns Either of an error message or the re-compiled base valuation
+ * report.
+ */
+export function recompileBaseValuationReport(x: RemoteBaseValuationReport): Either<CustomError, BaseValuationReport> {
+  const nav = maybeDecimal(x.nav).orDefault(zero);
+
+  const report: BaseValuationReport = {
+    asof: x.reported,
+    date: x.asof,
+    dateType: x.type,
+    currency: x.ccy,
+    accounts: x.accounts,
+    holdings: x.holdings.map((rh) => toHolding(nav, rh)),
+    accruals: x.accruals.map(toAccrual),
+    fxRates: x.fxrates.map((r) => ({ ccy1: r.ccy1, ccy2: r.ccy2, value: asDecimal(r.value), asof: r.asof })),
+    figures: {
+      investment: maybeDecimal(x.investment).orDefault(zero),
+      valuation: {
+        net: maybeDecimal(x.valuation_net).orDefault(zero),
+        abs: maybeDecimal(x.valuation_abs).orDefault(zero),
+      },
+      accrued: maybeDecimal(x.accrued).orDefault(zero),
+      liabilities: maybeDecimal(x.liabilities).orDefault(zero),
+      gav: maybeDecimal(x.gav).orDefault(zero),
+      nav,
+      aum: maybeDecimal(x.aum).orDefault(zero),
+      pnl: maybeDecimal(x.pnl).orDefault(zero),
+      pnlToInvestment: maybeDecimal(x.pnl_to_investment),
+    },
+  };
+
+  return Right(report);
+}

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

@@ -0,0 +1,46 @@
+import { BaseValuationReport } from './-valuation-report-shared';
+
+/**
+ * Type definition for consolidated valuation report.
+ */
+export interface ConsolidatedValuationReport extends BaseValuationReport {
+  /**
+   * Type of containers consolidated.
+   */
+  containerType: ConsolidatedValuationReportContainerType;
+
+  /**
+   * Containers consolidated.
+   */
+  containers: ConsolidatedValuationReportContainer[];
+}
+
+/**
+ * Type definition for container types to be consolidated.
+ */
+export type ConsolidatedValuationReportContainerType =
+  | 'account'
+  | 'portfolio'
+  | 'team'
+  | 'custodian'
+  | 'portfolio-group';
+
+/**
+ * Type definition for valuation report containers.
+ */
+export interface ConsolidatedValuationReportContainer {
+  /**
+   * Id of the container.
+   */
+  id: number;
+
+  /**
+   * GUID of the container.
+   */
+  guid: string;
+
+  /**
+   * Name of the container.
+   */
+  name: string;
+}

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

@@ -0,0 +1,171 @@
+import { Decimal, safeDiv, sumDecimals, Tuple, zero } from '@telostat/prelude';
+import { Just, Maybe, Nothing } from 'purify-ts';
+import { List } from 'purify-ts/List';
+import { ValuationReportHolding, ValuationReportHoldingClassification } from '../-valuation-report-shared';
+import { ValuationReportHoldingsTreeNode, ValuationReportHoldingsTreeNodeValue } from './-types';
+import { compareStringArrays } from './-utils';
+
+export function makeValuationReportHoldingsTreeNodeValue(): ValuationReportHoldingsTreeNodeValue {
+  return {
+    investment: zero,
+    accrued: Nothing,
+    netValue: zero,
+    netValueRatio: zero,
+    absValue: zero,
+    absValueRatio: zero,
+    netExposure: zero,
+    netExposureRatio: zero,
+    absExposure: zero,
+    absExposureRatio: zero,
+    pnl: zero,
+    pnlRatio: zero,
+  };
+}
+
+export function updateTotals(
+  nav: Decimal,
+  investment: Decimal,
+  tree: ValuationReportHoldingsTreeNode
+): ValuationReportHoldingsTreeNodeValue {
+  const holdings = tree.holdings;
+  const children = tree.children;
+
+  const netValue = sumDecimals(holdings.map((x) => x.valuation.value.net.ref)).add(
+    sumDecimals(children.map((x) => x.totals.netValue))
+  );
+  const absValue = sumDecimals(holdings.map((x) => x.valuation.value.abs.ref)).add(
+    sumDecimals(children.map((x) => x.totals.absValue))
+  );
+  const netExposure = sumDecimals(holdings.map((x) => x.valuation.exposure.net.ref)).add(
+    sumDecimals(children.map((x) => x.totals.netExposure))
+  );
+  const absExposure = sumDecimals(holdings.map((x) => x.valuation.exposure.abs.ref)).add(
+    sumDecimals(children.map((x) => x.totals.absExposure))
+  );
+  const pnl = sumDecimals(holdings.map((x) => x.pnl)).add(sumDecimals(children.map((x) => x.totals.pnl)));
+
+  const accruedsHoldings = holdings.map((x) => x.investment.accrued.map((x) => x.ref));
+  const accruedsChildren = children.map((x) => x.totals.accrued);
+  const accrueds = Maybe.catMaybes([...accruedsHoldings, ...accruedsChildren]);
+
+  return {
+    investment: sumDecimals(holdings.map((x) => x.investment.value.ref)).add(
+      sumDecimals(children.map((x) => x.totals.investment))
+    ),
+    accrued: accrueds.length === 0 ? Nothing : Just(sumDecimals(accrueds)),
+    netValue,
+    netValueRatio: safeDiv(netValue, nav).orDefault(zero),
+    absValue,
+    absValueRatio: safeDiv(absValue, nav).orDefault(zero),
+    netExposure,
+    netExposureRatio: safeDiv(netExposure, nav).orDefault(zero),
+    absExposure,
+    absExposureRatio: safeDiv(absExposure, nav).orDefault(zero),
+    pnl,
+    pnlRatio: safeDiv(pnl, investment).orDefault(zero),
+  };
+}
+
+export function resortChildren(node: ValuationReportHoldingsTreeNode): ValuationReportHoldingsTreeNode[] {
+  return node.children.sort((t1, t2) => {
+    // Get current address segments:
+    const segment1 = List.last(t1.address);
+    const segment2 = List.last(t2.address);
+
+    // Compare and return:
+    return segment1
+      .chain((s1) => segment2.chain((s2) => Just(Tuple(s1, s2))))
+      .map((x) => x.toArray())
+      .map(([x, y]) => `${x.order}`.localeCompare(`${y.order}`))
+      .orDefaultLazy(() => (segment1.isNothing() ? -1 : 1));
+  });
+}
+
+export function retreatTree(nav: Decimal, investment: Decimal, tree: ValuationReportHoldingsTreeNode) {
+  // First, retreat all children (recursive):
+  tree.children.forEach((x) => retreatTree(nav, investment, x));
+
+  // Recompute totals:
+  tree.totals = updateTotals(nav, investment, tree);
+
+  // Resort children:
+  tree.children = resortChildren(tree);
+}
+
+export function makeValuationReportHoldingsTreeNode(
+  address: ValuationReportHoldingClassification
+): ValuationReportHoldingsTreeNode {
+  return {
+    name: List.last(address)
+      .map((x) => x.name)
+      .orDefault(''),
+    address,
+    holdings: [],
+    children: [],
+    totals: makeValuationReportHoldingsTreeNodeValue(),
+  };
+}
+
+export function addValuationReportHoldingToTree(
+  tree: ValuationReportHoldingsTreeNode,
+  address: ValuationReportHoldingClassification,
+  holding: ValuationReportHolding
+): void {
+  // Get the starting (current) node:
+  let node = tree;
+
+  // Iterate over address and traverse the tree while adding new nodes when required:
+  const sofar: string[] = [];
+  const sofarAddress: ValuationReportHoldingClassification = [];
+
+  for (const segment of address) {
+    // Append to address buffer:
+    sofar.push(segment.name);
+    sofarAddress.push(segment);
+
+    // Attempt to find the child:
+    let child = node.children.find(
+      (n) =>
+        compareStringArrays(
+          n.address.map((x) => x.name),
+          sofar
+        ) === 0
+    );
+
+    // Add or use?
+    if (child === undefined) {
+      // Create the new node:
+      child = makeValuationReportHoldingsTreeNode([...sofarAddress]);
+
+      // Add the new node to the current node as a child:
+      node.children.push(child);
+    }
+
+    // Set the current node to the child:
+    node = child;
+  }
+
+  // Done, we append the holding to the current node and return from the procedure:
+  node.holdings.push(holding);
+}
+
+export function makeValuationReportHoldingsTree(
+  nav: Decimal,
+  investment: Decimal,
+  holdings: ValuationReportHolding[]
+): ValuationReportHoldingsTreeNode {
+  // Initialize the tree:
+  const tree = makeValuationReportHoldingsTreeNode([]);
+  tree.name = '« Total »';
+
+  // Iterate over the holdings and attempt to add to the tree:
+  for (const holding of holdings) {
+    addValuationReportHoldingToTree(tree, holding.classification, holding);
+  }
+
+  // Retreat the tree:
+  retreatTree(nav, investment, tree);
+
+  // Done, return:
+  return tree;
+}

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

@@ -0,0 +1,25 @@
+import { Decimal, Maybe } from '@telostat/prelude';
+import { ValuationReportHolding, ValuationReportHoldingClassification } from '../-valuation-report-shared';
+
+export interface ValuationReportHoldingsTreeNode {
+  name: string;
+  address: ValuationReportHoldingClassification;
+  holdings: ValuationReportHolding[];
+  children: ValuationReportHoldingsTreeNode[];
+  totals: ValuationReportHoldingsTreeNodeValue;
+}
+
+export interface ValuationReportHoldingsTreeNodeValue {
+  investment: Decimal;
+  accrued: Maybe<Decimal>;
+  netValue: Decimal;
+  netValueRatio: Decimal;
+  absValue: Decimal;
+  absValueRatio: Decimal;
+  netExposure: Decimal;
+  netExposureRatio: Decimal;
+  absExposure: Decimal;
+  absExposureRatio: Decimal;
+  pnl: Decimal;
+  pnlRatio: Decimal;
+}

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

@@ -0,0 +1,15 @@
+export function compareStringArrays(x: string[], y: string[]): number {
+  const xLen = x.length;
+  const yLen = y.length;
+  const minLength = Math.min(xLen, yLen);
+
+  for (let i = 0; i < minLength; i++) {
+    const comparison = (x[i] || '').localeCompare(y[i] || '');
+
+    if (comparison !== 0) {
+      return comparison;
+    }
+  }
+
+  return Math.sign(xLen - yLen);
+}

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

@@ -0,0 +1,2 @@
+export { makeValuationReportHoldingsTree } from './-machinery';
+export * from './-types';

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

@@ -0,0 +1,92 @@
+import { Decimal, Maybe, SDate, SDateTime } from '@telostat/prelude';
+import {
+  ActionId,
+  CurrencyCode,
+  ExternalValuationId,
+  OhlcSeriesId,
+  PortfolioId,
+  PrincipalId,
+  ShareClassFeeScheduleId,
+  ShareClassId,
+} from '../../commons';
+import { BaseValuationReport, ValuationReportPortfolio } from './-valuation-report-shared';
+
+export interface PortfolioValuationReport extends BaseValuationReport {
+  portfolio: ValuationReportPortfolio;
+  subscriptions: Decimal;
+  shareClassValues: PortfolioValuationReportShareClassValue[];
+}
+
+export interface PortfolioValuationReportShareClassValue {
+  shareclass: PortfolioValuationReportShareClass;
+  external: Maybe<PortfolioValuationReportExternalValue>;
+  nav: Decimal;
+  navAdjusted: Decimal;
+  navAdjustedTotal: Decimal;
+  coefficient: Decimal;
+  gavRefccy: Decimal;
+  gavClsccy: Decimal;
+  sharecountPrev: Decimal;
+  sharecountCurr: Decimal;
+  sharecountDiff: Decimal;
+  pxRefCcy: Decimal;
+  pxClsCcy: Decimal;
+  ytdExt: Maybe<Decimal>;
+  ytdInt: Maybe<Decimal>;
+}
+
+export interface PortfolioValuationReportShareClass {
+  id: ShareClassId;
+  created: SDateTime;
+  creator: Maybe<PrincipalId>;
+  updated: SDateTime;
+  updater: Maybe<PrincipalId>;
+  guid: string;
+  portfolio: PortfolioId;
+  name: string;
+  currency: CurrencyCode;
+  isin: Maybe<string>;
+  bbgticker: Maybe<string>;
+  liquidity: Maybe<string>;
+  jurisdiction: Maybe<string>;
+  administrator: Maybe<string>;
+  minimumInvestment: Maybe<string>;
+  subscriptionRedemptionPeriod: Maybe<string>;
+  managementFeeFrequency: Maybe<number>;
+  performanceFeeFrequency: Maybe<number>;
+  benchmark: Maybe<OhlcSeriesId>;
+  description: Maybe<string>;
+  feeScheduleIds: ShareClassFeeScheduleId[];
+  effectiveFeeScheduleId: Maybe<ShareClassFeeScheduleId>;
+  subscriptionIds: ActionId[];
+  outstanding: Maybe<Decimal>;
+}
+
+export interface PortfolioValuationReportExternalValue {
+  id: ExternalValuationId;
+  created: SDateTime;
+  creator: Maybe<PrincipalId>;
+  updated: SDateTime;
+  updater: Maybe<PrincipalId>;
+  guid: string;
+  portfolio: PortfolioId;
+  shareclass: Maybe<ShareClassId>;
+  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>;
+}