@wealthfolio/addon-sdk 3.3.0 → 3.6.0

package/dist/src/data-types.d.ts

@@ -82,6 +82,7 @@ export type DataSource = (typeof DataSource)[keyof typeof DataSource];
 export declare const AccountType: {
     readonly SECURITIES: "SECURITIES";
     readonly CASH: "CASH";
+    readonly CREDIT_CARD: "CREDIT_CARD";
     readonly CRYPTOCURRENCY: "CRYPTOCURRENCY";
 };
 export type AccountType = (typeof AccountType)[keyof typeof AccountType];
@@ -129,6 +130,7 @@ export interface Activity {
     unitPrice?: string | null;
     amount?: string | null;
     fee?: string | null;
+    tax?: string | null;
     currency: string;
     fxRate?: string | null;
     notes?: string;
@@ -161,6 +163,7 @@ export interface ActivityDetails {
     unitPrice: string | null;
     amount: string | null;
     fee: string | null;
+    tax?: string | null;
     currency: string;
     needsReview: boolean;
     comment?: string;
@@ -198,6 +201,8 @@ export interface AssetResolutionInput {
     quoteMode?: QuoteMode;
     quoteCcy?: string;
     instrumentType?: string;
+    providerId?: string;
+    providerSymbol?: string;
 }
 /** @deprecated Use AssetResolutionInput. */
 export type SymbolInput = AssetResolutionInput;
@@ -216,6 +221,7 @@ export interface ActivityCreate {
     amount?: string | number | null;
     currency?: string;
     fee?: string | number | null;
+    tax?: string | number | null;
     comment?: string | null;
     fxRate?: string | number | null;
     metadata?: string | Record<string, unknown>;
@@ -235,6 +241,7 @@ export interface ActivityUpdate {
     amount?: string | number | null;
     currency?: string;
     fee?: string | number | null;
+    tax?: string | number | null;
     comment?: string | null;
     fxRate?: string | number | null;
     metadata?: string | Record<string, unknown>;
@@ -273,6 +280,7 @@ export interface ActivityImport {
     quantity?: number | string | null;
     unitPrice?: number | string | null;
     fee?: number | string | null;
+    tax?: number | string | null;
     fxRate?: number | string | null;
     accountName?: string;
     symbolName?: string;
@@ -284,6 +292,10 @@ export interface ActivityImport {
     instrumentType?: string;
     /** Resolved quote mode hint (e.g., MANUAL, MARKET) */
     quoteMode?: string;
+    /** Market data provider that resolved this import row, if selected. */
+    providerId?: string;
+    /** Provider-native symbol/code selected by search/import. */
+    providerSymbol?: string;
     errors?: Record<string, string[]>;
     warnings?: Record<string, string[]>;
     duplicateOfId?: string;
@@ -318,6 +330,14 @@ export interface SymbolSearchResult {
     exchange: string;
     /** Canonical exchange MIC code (e.g., "XNAS", "XTSE") */
     exchangeMic?: string;
+    /** Canonical asset symbol used for persistence (e.g., "SHOP" for "SHOP.TO") */
+    canonicalSymbol?: string;
+    /** Canonical exchange MIC used for persistence */
+    canonicalExchangeMic?: string;
+    /** Market data provider that returned or resolved this symbol */
+    providerId?: string;
+    /** Provider-native symbol/code (e.g., Yahoo "BRK-B") */
+    providerSymbol?: string;
     /** Friendly exchange name (e.g., "NASDAQ" instead of "NMS" or "XNAS") */
     exchangeName?: string;
     /** Currency derived from exchange (e.g., "USD", "CAD") */
@@ -453,6 +473,10 @@ export interface Holding {
     realizedGainPct?: number | null;
     totalGain?: MonetaryValue | null;
     totalGainPct?: number | null;
+    income?: MonetaryValue | null;
+    totalReturn?: MonetaryValue | null;
+    totalReturnPct?: number | null;
+    returnBasis?: MonetaryValue | null;
     dayChange?: MonetaryValue | null;
     dayChangePct?: number | null;
     prevCloseValue?: MonetaryValue | null;
@@ -511,6 +535,7 @@ export interface Settings {
     theme: string;
     font: string;
     baseCurrency: string;
+    defaultReturnMetric: 'twr' | 'irr' | 'valueReturn';
     timezone?: string;
     instanceId: string;
     onboardingCompleted: boolean;
@@ -583,6 +608,8 @@ export interface DateRange {
     to: Date | undefined;
 }
 export type TimePeriod = '1D' | '1W' | '1M' | '3M' | '6M' | 'YTD' | '1Y' | '5Y' | 'ALL';
+export type ValuationStatus = 'complete' | 'partialUnpriced' | 'unavailable';
+export type BasisStatus = 'complete' | 'partialUnknown' | 'unknown' | 'notApplicable';
 export interface AccountValuation {
     id: string;
     accountId: string;
@@ -595,6 +622,17 @@ export interface AccountValuation {
     totalValue: number;
     costBasis: number;
     netContribution: number;
+    cashBalanceBase: number;
+    investmentMarketValueBase: number;
+    totalValueBase: number;
+    costBasisBase: number;
+    netContributionBase: number;
+    externalInflowBase: number;
+    externalOutflowBase: number;
+    externalFlowSource: 'NO_FLOW' | 'UNKNOWN' | 'CASH_AMOUNT' | 'QUOTE_DERIVED_MARKET_VALUE' | 'COST_BASIS_FALLBACK' | 'REMOVED_LOT_BASIS_FALLBACK' | 'LEGACY_ACTIVITY_AMOUNT_FALLBACK' | 'UNKNOWN_BOUNDARY_TRANSFER' | 'ACTIVITY_DERIVED' | 'STORED_GROSS' | 'NET_CONTRIBUTION_FALLBACK' | 'MIXED';
+    performanceEligibleValueBase: number;
+    valueStatus: ValuationStatus;
+    basisStatus: BasisStatus;
     calculatedAt: string;
 }
 export interface AccountSummaryView {
@@ -606,9 +644,9 @@ export interface AccountSummaryView {
     totalValueAccountCurrency: number;
     totalValueBaseCurrency: number;
     baseCurrency: string;
-    performance: SimplePerformanceMetrics;
+    performance: SimplePerformanceResult;
 }
-export interface SimplePerformanceMetrics {
+export interface SimplePerformanceResult {
     accountId: string;
     totalValue?: number | null;
     accountCurrency?: string | null;
@@ -616,16 +654,16 @@ export interface SimplePerformanceMetrics {
     fxRateToBase?: number | null;
     totalGainLossAmount?: number | null;
     cumulativeReturnPercent?: number | null;
-    dayGainLossAmount?: number | null;
-    dayReturnPercentModDietz?: number | null;
     portfolioWeight?: number | null;
 }
+/** @deprecated Use SimplePerformanceResult. */
+export type SimplePerformanceMetrics = SimplePerformanceResult;
 export interface AccountGroup {
     groupName: string;
     accounts: AccountSummaryView[];
     totalValueBaseCurrency: number;
     baseCurrency: string;
-    performance: SimplePerformanceMetrics;
+    performance: SimplePerformanceResult;
     accountCount: number;
 }
 export interface ExchangeRate {
@@ -666,32 +704,77 @@ export interface ReturnData {
     date: string;
     value: number;
 }
-export interface PerformanceMetrics {
+export interface PerformanceResult {
+    scope: PerformanceScopeDescriptor;
+    period: PerformancePeriod;
+    mode: ReturnMethod;
+    returns: PerformanceReturns;
+    attribution: PerformanceAttribution;
+    risk: PerformanceRisk;
+    dataQuality: PerformanceDataQuality;
+    basisStatus?: BasisStatus;
+    summary?: PerformanceSummary;
+    series: ReturnData[];
+    isHoldingsMode?: boolean;
+    isMixedTrackingMode?: boolean;
+}
+/** @deprecated Use PerformanceResult. */
+export type PerformanceMetrics = PerformanceResult;
+export interface PerformanceScopeDescriptor {
     id: string;
-    returns: ReturnData[];
-    periodStartDate?: string | null;
-    periodEndDate?: string | null;
     currency: string;
-    /** Period gain in dollars (SOTA: change in unrealized P&L for HOLDINGS mode) */
-    periodGain: number;
-    /** Period return percentage (SOTA formula for HOLDINGS mode). Null when start value ≤ 0. */
-    periodReturn: number | null;
-    /** Time-weighted return (null for HOLDINGS mode - requires cash flow tracking) */
-    cumulativeTwr?: number | null;
-    /** Legacy field for backward compatibility */
-    gainLossAmount?: number | null;
-    /** Annualized TWR (null for HOLDINGS mode) */
+}
+export interface PerformancePeriod {
+    startDate?: string | null;
+    endDate?: string | null;
+}
+export type ReturnMethod = 'timeWeighted' | 'valueReturn' | 'symbolPriceBased' | 'notApplicable';
+export type PerformanceSummaryBasis = 'marketValue' | 'bookBasis' | 'mixed' | 'notApplicable';
+export type PerformanceSummaryStatus = 'complete' | 'unavailable';
+export interface PerformanceSummary {
+    amount?: number | null;
+    percent?: number | null;
+    method: ReturnMethod;
+    basis: PerformanceSummaryBasis;
+    quality: PerformanceDataQuality['status'];
+    amountStatus: PerformanceSummaryStatus;
+    percentStatus: PerformanceSummaryStatus;
+    basisStatus: BasisStatus;
+    reasons: string[];
+}
+export interface PerformanceReturns {
+    twr?: number | null;
     annualizedTwr?: number | null;
-    simpleReturn: number;
-    annualizedSimpleReturn: number;
-    /** Money-weighted return (null for HOLDINGS mode - requires cash flow tracking) */
-    cumulativeMwr?: number | null;
-    /** Annualized MWR (null for HOLDINGS mode) */
-    annualizedMwr?: number | null;
-    volatility: number;
-    maxDrawdown: number;
-    /** Indicates if this is a HOLDINGS mode account (no cash flow tracking) */
-    isHoldingsMode?: boolean;
+    /** Selected-period money-weighted return derived from annualized XIRR. */
+    irr?: number | null;
+    /** Annualized XIRR using dated cash flows. */
+    annualizedIrr?: number | null;
+    valueReturn?: number | null;
+    annualizedValueReturn?: number | null;
+}
+export interface PerformanceAttribution {
+    contributions: number;
+    distributions: number;
+    income: number;
+    realizedPnl: number;
+    unrealizedPnlChange: number;
+    fxEffect: number;
+    fees: number;
+    taxes: number;
+    residual: number;
+}
+export interface PerformanceRisk {
+    volatility?: number | null;
+    maxDrawdown?: number | null;
+    peakDate?: string | null;
+    troughDate?: string | null;
+    recoveryDate?: string | null;
+    drawdownDurationDays?: number | null;
+}
+export interface PerformanceDataQuality {
+    status: 'ok' | 'partial' | 'noData' | 'notApplicable';
+    warnings?: string[];
+    notApplicableReasons?: string[];
 }
 export interface UpdateAssetProfile {
     id: string;
@@ -766,6 +849,10 @@ export interface SnapshotHoldingInput {
     currency: string;
     averageCost?: string;
     exchangeMic?: string;
+    quoteCcy?: string;
+    instrumentType?: string;
+    providerId?: string;
+    providerSymbol?: string;
     name?: string;
     dataSource?: string;
     assetKind?: string;
@@ -776,6 +863,10 @@ export interface SnapshotPositionInput {
     avgCost?: string;
     currency: string;
     exchangeMic?: string;
+    quoteCcy?: string;
+    instrumentType?: string;
+    providerId?: string;
+    providerSymbol?: string;
 }
 export interface SnapshotInput {
     date: string;

package/dist/src/host-api.d.ts

@@ -3,7 +3,7 @@
  * Provides comprehensive access to Wealthfolio functionality organized by domain
  */
 import type { EventCallback, UnlistenFn } from './types';
-import type { Account, Activity, ActivityBulkMutationRequest, ActivityBulkMutationResult, ActivityCreate, ActivityDetails, ActivityImport, ActivitySearchResponse, ActivityUpdate, AccountValuation, CheckSnapshotImportResult, ImportActivitiesResult, Asset, ContributionLimit, DepositsCalculation, ExchangeRate, Goal, GoalAllocation, Holding, ImportMappingData, IncomeSummary, MarketDataProviderInfo, NewContributionLimit, PerformanceMetrics, Quote, Settings, SimplePerformanceMetrics, SnapshotHoldingInput, SnapshotImportResult, SnapshotInfo, SnapshotInput, SymbolSearchResult, UpdateAssetProfile } from './data-types';
+import type { Account, Activity, ActivityBulkMutationRequest, ActivityBulkMutationResult, ActivityCreate, ActivityDetails, ActivityImport, ActivitySearchResponse, ActivityUpdate, AccountValuation, CheckSnapshotImportResult, ImportActivitiesResult, Asset, ContributionLimit, DepositsCalculation, ExchangeRate, Goal, GoalAllocation, Holding, ImportMappingData, IncomeSummary, MarketDataProviderInfo, NewContributionLimit, PerformanceResult, Quote, Settings, SimplePerformanceResult, SnapshotHoldingInput, SnapshotImportResult, SnapshotInfo, SnapshotInput, SymbolSearchResult, UpdateAssetProfile } from './data-types';
 export interface ActivitySearchFilters {
     accountIds?: string | string[];
     activityTypes?: string | string[];
@@ -141,12 +141,20 @@ export interface ActivitiesAPI {
     saveImportMapping(mapping: ImportMappingData): Promise<ImportMappingData>;
 }
 /**
- * A single dividend event returned by Yahoo Finance.
+ * A cash dividend event returned by a market data provider.
  */
-export interface YahooDividend {
+export interface DividendEvent {
     amount: number;
     date: number;
 }
+export interface FetchDividendsOptions {
+    exchangeMic?: string;
+    instrumentType?: string;
+    quoteCcy?: string;
+    providerId?: string;
+    startDate?: string;
+    endDate?: string;
+}
 /**
  * Market data and asset APIs
  */
@@ -176,11 +184,11 @@ export interface MarketDataAPI {
      */
     getProviders(): Promise<MarketDataProviderInfo[]>;
     /**
-     * Fetch dividend history for a symbol from Yahoo Finance.
+     * Fetch dividend history for a symbol.
      * @param symbol Ticker symbol
      * @returns Promise resolving to array of dividend events
      */
-    fetchDividends(symbol: string): Promise<YahooDividend[]>;
+    fetchDividends(symbol: string, options?: FetchDividendsOptions): Promise<DividendEvent[]>;
 }
 /**
  * Asset management APIs
@@ -236,7 +244,7 @@ export interface PerformanceAPI {
      * @param endDate End date for calculation
      * @returns Promise resolving to performance metrics
      */
-    calculateHistory(itemType: 'account' | 'symbol', itemId: string, startDate: string, endDate: string): Promise<PerformanceMetrics>;
+    calculateHistory(itemType: 'account' | 'symbol', itemId: string, startDate?: string, endDate?: string): Promise<PerformanceResult>;
     /**
      * Calculate performance summary
      * @param args Performance calculation arguments
@@ -247,13 +255,13 @@ export interface PerformanceAPI {
         itemId: string;
         startDate?: string | null;
         endDate?: string | null;
-    }): Promise<PerformanceMetrics>;
+    }): Promise<PerformanceResult>;
     /**
      * Calculate simple performance for multiple accounts
      * @param accountIds Array of account identifiers
      * @returns Promise resolving to array of simple performance metrics
      */
-    calculateAccountsSimple(accountIds: string[]): Promise<SimplePerformanceMetrics[]>;
+    calculateAccountsSimple(accountIds: string[]): Promise<SimplePerformanceResult[]>;
 }
 /**
  * Exchange rates APIs
@@ -375,7 +383,6 @@ export interface SettingsAPI {
      */
     backupDatabase(): Promise<{
         filename: string;
-        data: Uint8Array;
     }>;
 }
 /**
@@ -578,6 +585,28 @@ export interface QueryAPI {
      */
     refetchQueries(queryKey: string | string[]): void;
 }
+export interface NetworkRequest {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+    headers?: Record<string, string>;
+    body?: string;
+    auth?: NetworkAuth;
+}
+export interface NetworkResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface NetworkAuth {
+    type: 'bearer';
+    secretKey: string;
+}
+export interface NetworkAPI {
+    /**
+     * Send a brokered HTTPS request to a host declared in the addon manifest.
+     */
+    request(request: NetworkRequest): Promise<NetworkResponse>;
+}
 /**
  * Snapshot management APIs
  * For accounts using HOLDINGS tracking mode
@@ -631,6 +660,8 @@ export interface HostAPI {
     navigation: NavigationAPI;
     /** React Query operations */
     query: QueryAPI;
+    /** Brokered external network operations */
+    network: NetworkAPI;
     /** Toast notification operations */
     toast: ToastAPI;
 }

package/dist/src/host-dependencies.d.ts

@@ -0,0 +1,10 @@
+export declare const HOST_DEPENDENCIES: {
+    readonly '@tanstack/react-query': "^5.90.0";
+    readonly '@wealthfolio/addon-sdk': "^3.6.0";
+    readonly '@wealthfolio/ui': "^3.6.0";
+    readonly 'date-fns': "^4.1.0";
+    readonly 'lucide-react': "^0.561.0";
+    readonly react: "^19.2.0";
+    readonly 'react-dom': "^19.2.0";
+    readonly recharts: "^3.7.0";
+};

package/dist/src/index.d.ts

@@ -8,22 +8,32 @@
  * @author Wealthfolio Team
  * @license MIT
  */
-export type { AddonContext, AddonEnableFunction, EventCallback, RouteConfig, RouterManager, SidebarItemConfig, SidebarItemHandle, SidebarManager, UnlistenFn, } from './types';
-export type { ActivitySearchFilters, ActivitySort, HostAPI, SnapshotsAPI, ToastAPI, YahooDividend, } from './host-api';
+export type { AddonContext, AddonEnableFunction, AddonRouteLocation, AddonRouteRenderContext, AddonRouteRenderer, EventCallback, RouteConfig, RouterManager, SidebarItemConfig, SidebarItemHandle, SidebarManager, UnlistenFn, } from './types';
+export type { ActivitySearchFilters, ActivitySort, HostAPI, NetworkAuth, NetworkAPI, NetworkRequest, NetworkResponse, SnapshotsAPI, ToastAPI, DividendEvent, FetchDividendsOptions, } from './host-api';
 export type { QueryClient } from '@tanstack/react-query';
 export { QueryKeys } from './query-keys';
 export type * from './data-types';
-export type { AddonFile, AddonInstallResult, AddonManifest, AddonStoreListing, AddonUpdateCheckResult, AddonUpdateInfo, AddonValidationResult, DevelopmentManifest, ExtractedAddon, InstalledAddon, InstalledManifest, } from './manifest';
+export type { AddonFile, AddonHostDependencies, AddonInstallResult, AddonManifest, AddonStoreListing, AddonUpdateCheckResult, AddonUpdateInfo, AddonValidationResult, DevelopmentManifest, ExtractedAddon, InstalledAddon, InstalledManifest, } from './manifest';
 export { isInstalledManifest } from './manifest';
 export type { FunctionPermission, Permission, PermissionCategory, RiskLevel, } from './permissions';
 export { getFunctionRiskLevel, getPermissionCategoriesByRisk, getPermissionCategory, isPermissionRequired, PERMISSION_CATEGORIES, } from './permissions';
 export { formatAddonSize, generateAddonId, isAddonManifest, isCompatibleVersion, validateManifest, } from './utils';
 export { calculateGoalProgress } from './goal-progress';
 /**
- * React version guaranteed by the host application. Addons may assert against
- * this at runtime if they rely on a particular React feature set.
+ * React version provided by the Wealthfolio add-on sandbox for host-externalized
+ * add-ons.
+ */
+export declare const ReactVersion = "19.2.4";
+export { HOST_DEPENDENCIES } from './host-dependencies';
+/**
+ * Addons receive their context as a parameter to the enable() function.
+ * Each addon gets its own isolated iframe context with scoped host APIs.
+ *
+ * Example:
+ * export default function enable(ctx: AddonContext) {
+ *   // Use ctx.api.secrets.set/get/delete for secure storage
+ *   // Use ctx.sidebar.addItem() to add navigation
+ *   // Use ctx.router.add() with a render callback to register routes
+ * }
  */
-export declare const ReactVersion = "19.1.1";
-export declare const React: typeof import("react");
-export declare const ReactDOM: typeof import("react-dom");
 export { SDK_VERSION } from './version';

package/dist/src/manifest.d.ts

@@ -2,6 +2,11 @@
  * Addon manifest and metadata types
  */
 import type { Permission } from './permissions';
+export interface AddonNetworkAccess {
+    allowedHosts: string[];
+    approvedHosts?: string[];
+}
+export type AddonHostDependencies = Record<string, string>;
 /**
  * Unified addon manifest structure that handles both development and runtime scenarios
  * This represents both what developers write in their manifest.json and installed addon metadata
@@ -37,6 +42,10 @@ export interface AddonManifest {
     keywords?: string[];
     /** Addon icon (base64 or relative path) */
     icon?: string;
+    /** Network hosts this addon may reach through the host broker */
+    network?: AddonNetworkAccess;
+    /** Host-provided packages this addon imports instead of bundling */
+    hostDependencies?: AddonHostDependencies;
     /** Installation timestamp in ISO format */
     installedAt?: string;
     /** Last update timestamp */
@@ -125,6 +134,8 @@ export interface AddonUpdateInfo {
     updateAvailable: boolean;
     /** Download URL for the update */
     downloadUrl?: string;
+    /** Optional SHA-256 digest for the update package bytes */
+    sha256?: string;
     /** Release notes for the latest version */
     releaseNotes?: string;
     /** Release date of the latest version */
@@ -157,6 +168,8 @@ export interface AddonStoreListing {
     metadata: AddonManifest;
     /** Download URL */
     downloadUrl: string;
+    /** Optional SHA-256 digest for the package bytes */
+    sha256?: string;
     /** Number of downloads */
     downloads?: number;
     /** Average rating */

package/dist/src/types.d.ts

@@ -1,4 +1,3 @@
-import React from 'react';
 import type { HostAPI } from './host-api';
 /**
  * Core types for addon development
@@ -18,23 +17,45 @@ export interface SidebarItemConfig {
     id: string;
     /** Display text for the sidebar item */
     label: string;
-    /** Optional icon name or React component */
-    icon?: string | React.ReactNode;
+    /** Optional host-supported icon name */
+    icon?: string;
     /** Optional route to navigate to when clicked */
     route?: string;
     /** Optional ordering priority (lower numbers appear first) */
     order?: number;
-    /** Optional click handler (if no route provided) */
-    onClick?: () => void;
 }
+/**
+ * Route location supplied by the host when an addon route is rendered.
+ */
+export interface AddonRouteLocation {
+    pathname: string;
+    search: string;
+    hash: string;
+    params: Record<string, string | undefined>;
+}
+/**
+ * Context supplied to addon route render functions.
+ */
+export interface AddonRouteRenderContext {
+    root: HTMLElement;
+    location: AddonRouteLocation;
+}
+/**
+ * Render callback for iframe-hosted addon routes.
+ */
+export type AddonRouteRenderer = (context: AddonRouteRenderContext) => void | Promise<void>;
 /**
  * Configuration for adding a route
  */
 export interface RouteConfig {
+    /** Optional stable route identifier */
+    id?: string;
     /** Route path pattern */
     path: string;
-    /** Lazy-loaded React component */
-    component: React.LazyExoticComponent<React.ComponentType<unknown>>;
+    /** Optional label for diagnostics */
+    title?: string;
+    /** Render inside the addon's sandboxed iframe */
+    render: AddonRouteRenderer;
 }
 /**
  * Sidebar management interface
@@ -71,6 +92,11 @@ export type UnlistenFn = () => void;
  * Main addon context interface providing access to Wealthfolio APIs
  */
 export interface AddonContext {
+    /** UI primitives owned by the addon's sandboxed iframe */
+    ui: {
+        /** Root element for addon-rendered content */
+        root: HTMLElement;
+    };
     /** Sidebar management */
     sidebar: SidebarManager;
     /** Router management */