@decafhub/decaf-client-extras 0.4.0 → 0.5.1

package/.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        node: [18, 20, 21]
+        node: [18, 20, 22]
         os: [ubuntu-latest]
     steps:
       - uses: actions/checkout@v4

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.0"
+  ".": "0.5.1"
 }

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.5.1](https://github.com/teloscube/decaf-client-javascript-extras/compare/v0.5.0...v0.5.1) (2024-08-31)
+
+
+### Bug Fixes
+
+* make grouping option configurable for holdings tree function ([ae97991](https://github.com/teloscube/decaf-client-javascript-extras/commit/ae97991f23393d04d85f782baedbd635a247db88))
+
+## [0.5.0](https://github.com/teloscube/decaf-client-javascript-extras/compare/v0.4.0...v0.5.0) (2024-08-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* drop support for Node 16 and add Node 22
+
+### Features
+
+* implement account valuation report ([26cb078](https://github.com/teloscube/decaf-client-javascript-extras/commit/26cb078a3e9a13811366be1f22b25326bdc79fa9))
+
+
+### Miscellaneous Chores
+
+* drop support for Node 16 and add Node 22 ([e23f398](https://github.com/teloscube/decaf-client-javascript-extras/commit/e23f398d19e1c95630e690ed8323e0561afae787))
+
 ## [0.4.0](https://github.com/teloscube/decaf-client-javascript-extras/compare/v0.3.0...v0.4.0) (2024-03-28)
 
 

package/es/reports/valuation/-remote-valuation-report-account.d.ts

@@ -0,0 +1,150 @@
+import { DecafClient } from '@decafhub/decaf-client';
+import { CustomError, Either, SDate, SDateTime } from '@telostat/prelude';
+import { CurrencyCode, DateType, DecafAccountId, DecafActionId, DecafExternalValuationId, DecafOhlcSeriesId, DecafPortfolioId, DecafPrincipalId, DecafShareClassFeeScheduleId, DecafShareClassId } from '../../commons';
+import { 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 declare function fetchRemoteAccountValuationReport(client: DecafClient, query: AccountValuationReportQuery): Promise<Either<CustomError, RemoteAccountValuationReport>>;
+/**
+ * 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 declare function toShareClassValue(s: RemoteValuationShareClassValue): AccountValuationReportShareClassValue;
+/**
+ * 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 declare function recompileAccountValuationReport(x: RemoteAccountValuationReport): Either<CustomError, AccountValuationReport>;
+/**
+ * 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 declare function fetchAccountValuationReport(client: DecafClient, query: AccountValuationReportQuery): Promise<Either<CustomError, AccountValuationReport>>;

package/es/reports/valuation/-remote-valuation-report-account.js

@@ -0,0 +1,135 @@
+import { customError, decimalFromNullable, Left, Maybe, Right, sanitizedNonEmptyText, unsafeDecimal, zero, } from '@telostat/prelude';
+import { recompileBaseValuationReport } from './-remote-valuation-report-shared';
+/**
+ * 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, query) {
+    return client.barista
+        .get('/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) {
+    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) {
+    // 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, query) {
+    // 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/es/reports/valuation/-valuation-report-account.d.ts

@@ -0,0 +1,79 @@
+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/es/reports/valuation/-valuation-report-account.js

@@ -0,0 +1 @@
+export {};

package/es/reports/valuation/-valuation-report-holdings-tree/-machinery.d.ts

@@ -1,10 +1,10 @@
 import { Decimal } from '@telostat/prelude';
 import { ValuationReportHolding, ValuationReportHoldingClassification } from '../-valuation-report-shared';
-import { ValuationReportHoldingsTreeNode, ValuationReportHoldingsTreeNodeValue } from './-types';
+import { AvailableAddresserKeys, ValuationReportHoldingsTreeNode, ValuationReportHoldingsTreeNodeValue } from './-types';
 export declare function makeValuationReportHoldingsTreeNodeValue(): ValuationReportHoldingsTreeNodeValue;
 export declare function updateTotals(nav: Decimal, investment: Decimal, tree: ValuationReportHoldingsTreeNode): ValuationReportHoldingsTreeNodeValue;
 export declare function resortChildren(node: ValuationReportHoldingsTreeNode): ValuationReportHoldingsTreeNode[];
 export declare function retreatTree(nav: Decimal, investment: Decimal, tree: ValuationReportHoldingsTreeNode): void;
 export declare function makeValuationReportHoldingsTreeNode(address: ValuationReportHoldingClassification): ValuationReportHoldingsTreeNode;
 export declare function addValuationReportHoldingToTree(tree: ValuationReportHoldingsTreeNode, address: ValuationReportHoldingClassification, holding: ValuationReportHolding): void;
-export declare function makeValuationReportHoldingsTree(nav: Decimal, investment: Decimal, holdings: ValuationReportHolding[]): ValuationReportHoldingsTreeNode;
+export declare function makeValuationReportHoldingsTree(nav: Decimal, investment: Decimal, holdings: ValuationReportHolding[], addressKey?: AvailableAddresserKeys): ValuationReportHoldingsTreeNode;

package/es/reports/valuation/-valuation-report-holdings-tree/-machinery.js

@@ -1,5 +1,5 @@
 import { Just, List, Maybe, Nothing, safeDiv, sumDecimals, Tuple, zero } from '@telostat/prelude';
-import { compareStringArrays } from './-utils';
+import { addressers, compareStringArrays } from './-utils';
 export function makeValuationReportHoldingsTreeNodeValue() {
     return {
         investment: zero,
@@ -102,13 +102,15 @@ export function addValuationReportHoldingToTree(tree, address, holding) {
     // Done, we append the holding to the current node and return from the procedure:
     node.holdings.push(holding);
 }
-export function makeValuationReportHoldingsTree(nav, investment, holdings) {
+export function makeValuationReportHoldingsTree(nav, investment, holdings, addressKey = 'classification') {
     // 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);
+        // Get the address of the holding:
+        const address = addressers[addressKey](holding);
+        addValuationReportHoldingToTree(tree, address, holding);
     }
     // Retreat the tree:
     retreatTree(nav, investment, tree);

package/es/reports/valuation/-valuation-report-holdings-tree/-types.d.ts

@@ -21,3 +21,6 @@ export interface ValuationReportHoldingsTreeNodeValue {
     pnl: Decimal;
     pnlRatio: Decimal;
 }
+export type HoldingAddress = ValuationReportHoldingClassification;
+export type HoldingAddresser = (holding: ValuationReportHolding) => HoldingAddress;
+export type AvailableAddresserKeys = 'classification' | 'currency' | 'country' | 'issuer' | 'sector';

package/es/reports/valuation/-valuation-report-holdings-tree/-utils.d.ts

@@ -1 +1,7 @@
+import { Maybe } from '@telostat/prelude';
+import { ValuationReportHolding } from '../-valuation-report-shared';
+import { AvailableAddresserKeys, HoldingAddresser } from './-types';
 export declare function compareStringArrays(x: string[], y: string[]): number;
+export declare function composeHoldingAddressers(addressers: Array<HoldingAddresser>): HoldingAddresser;
+export declare function makeSimpleAddresser(def: string, labeler: (holding: ValuationReportHolding) => Maybe<string>): HoldingAddresser;
+export declare const addressers: Record<AvailableAddresserKeys, HoldingAddresser>;

package/es/reports/valuation/-valuation-report-holdings-tree/-utils.js

@@ -10,3 +10,32 @@ export function compareStringArrays(x, y) {
     }
     return Math.sign(xLen - yLen);
 }
+export function composeHoldingAddressers(addressers) {
+    return (holding) => addressers.reduce((p, c) => [...p, ...c(holding)], []);
+}
+export function makeSimpleAddresser(def, labeler) {
+    return (holding) => {
+        // 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 = {
+    classification: (holding) => {
+        // 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) => holding.artifact.ccy),
+    country: makeSimpleAddresser('[Undefined Country]', (holding) => holding.artifact.country),
+    issuer: makeSimpleAddresser('[Undefined Issuer]', (holding) => holding.artifact.issuer),
+    sector: makeSimpleAddresser('[Undefined Sector]', (holding) => holding.artifact.sector),
+};

package/es/reports/valuation/index.d.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';

package/es/reports/valuation/index.js

@@ -1,6 +1,8 @@
 export { fetchConsolidatedValuationReport } from './-remote-valuation-report-consolidated';
 export { fetchPortfolioValuationReport } from './-remote-valuation-report-portfolio';
+export { fetchAccountValuationReport } 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decafhub/decaf-client-extras",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "DECAF Client Extras",
   "author": "Teloscube Pte Ltd",
   "license": "MIT",

package/release-please-config.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
   "packages": {
     ".": {
       "bump-minor-pre-major": true,