@wealthfolio/addon-sdk 1.0.0 → 3.0.0

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

@@ -0,0 +1,713 @@
+/**
+ * Comprehensive data types for Wealthfolio addons
+ * These types mirror the main application types to ensure compatibility
+ */
+export declare const ActivityType: {
+    readonly BUY: "BUY";
+    readonly SELL: "SELL";
+    readonly SPLIT: "SPLIT";
+    readonly DIVIDEND: "DIVIDEND";
+    readonly INTEREST: "INTEREST";
+    readonly DEPOSIT: "DEPOSIT";
+    readonly WITHDRAWAL: "WITHDRAWAL";
+    readonly TRANSFER_IN: "TRANSFER_IN";
+    readonly TRANSFER_OUT: "TRANSFER_OUT";
+    readonly FEE: "FEE";
+    readonly TAX: "TAX";
+    readonly CREDIT: "CREDIT";
+    readonly ADJUSTMENT: "ADJUSTMENT";
+    readonly UNKNOWN: "UNKNOWN";
+};
+export type ActivityType = (typeof ActivityType)[keyof typeof ActivityType];
+export declare const ACTIVITY_TYPES: readonly ["BUY", "SELL", "SPLIT", "DIVIDEND", "INTEREST", "DEPOSIT", "WITHDRAWAL", "TRANSFER_IN", "TRANSFER_OUT", "FEE", "TAX", "CREDIT", "ADJUSTMENT", "UNKNOWN"];
+export declare const ActivityStatus: {
+    readonly POSTED: "POSTED";
+    readonly PENDING: "PENDING";
+    readonly DRAFT: "DRAFT";
+    readonly VOID: "VOID";
+};
+export type ActivityStatus = (typeof ActivityStatus)[keyof typeof ActivityStatus];
+export declare const ACTIVITY_SUBTYPES: {
+    readonly DRIP: "DRIP";
+    readonly QUALIFIED: "QUALIFIED";
+    readonly ORDINARY: "ORDINARY";
+    readonly RETURN_OF_CAPITAL: "RETURN_OF_CAPITAL";
+    readonly DIVIDEND_IN_KIND: "DIVIDEND_IN_KIND";
+    readonly STAKING_REWARD: "STAKING_REWARD";
+    readonly LENDING_INTEREST: "LENDING_INTEREST";
+    readonly COUPON: "COUPON";
+    readonly REVERSE_SPLIT: "REVERSE_SPLIT";
+    readonly OPTION_OPEN: "OPTION_OPEN";
+    readonly OPTION_CLOSE: "OPTION_CLOSE";
+    readonly OPTION_EXPIRE: "OPTION_EXPIRE";
+    readonly OPTION_ASSIGNMENT: "OPTION_ASSIGNMENT";
+    readonly OPTION_EXERCISE: "OPTION_EXERCISE";
+    readonly MANAGEMENT_FEE: "MANAGEMENT_FEE";
+    readonly ADR_FEE: "ADR_FEE";
+    readonly INTEREST_CHARGE: "INTEREST_CHARGE";
+    readonly WITHHOLDING: "WITHHOLDING";
+    readonly NRA_WITHHOLDING: "NRA_WITHHOLDING";
+    readonly FEE_REFUND: "FEE_REFUND";
+    readonly TAX_REFUND: "TAX_REFUND";
+    readonly BONUS: "BONUS";
+    readonly ADJUSTMENT: "ADJUSTMENT";
+    readonly REBATE: "REBATE";
+    readonly REVERSAL: "REVERSAL";
+    readonly LIABILITY_INTEREST_ACCRUAL: "LIABILITY_INTEREST_ACCRUAL";
+    readonly LIABILITY_PRINCIPAL_PAYMENT: "LIABILITY_PRINCIPAL_PAYMENT";
+};
+export type ActivitySubtype = (typeof ACTIVITY_SUBTYPES)[keyof typeof ACTIVITY_SUBTYPES];
+export declare const AssetKind: {
+    readonly INVESTMENT: "INVESTMENT";
+    readonly PROPERTY: "PROPERTY";
+    readonly VEHICLE: "VEHICLE";
+    readonly COLLECTIBLE: "COLLECTIBLE";
+    readonly PRECIOUS_METAL: "PRECIOUS_METAL";
+    readonly PRIVATE_EQUITY: "PRIVATE_EQUITY";
+    readonly LIABILITY: "LIABILITY";
+    readonly OTHER: "OTHER";
+    readonly FX: "FX";
+};
+export type AssetKind = (typeof AssetKind)[keyof typeof AssetKind];
+export declare const QuoteMode: {
+    readonly MARKET: "MARKET";
+    readonly MANUAL: "MANUAL";
+};
+export type QuoteMode = (typeof QuoteMode)[keyof typeof QuoteMode];
+export declare const DataSource: {
+    readonly YAHOO: "YAHOO";
+    readonly MANUAL: "MANUAL";
+};
+export type DataSource = (typeof DataSource)[keyof typeof DataSource];
+export declare const AccountType: {
+    readonly SECURITIES: "SECURITIES";
+    readonly CASH: "CASH";
+    readonly CRYPTOCURRENCY: "CRYPTOCURRENCY";
+};
+export type AccountType = (typeof AccountType)[keyof typeof AccountType];
+export declare const HoldingType: {
+    readonly CASH: "cash";
+    readonly SECURITY: "security";
+    readonly ALTERNATIVE_ASSET: "AlternativeAsset";
+};
+export type HoldingType = (typeof HoldingType)[keyof typeof HoldingType];
+export type ImportRequiredField = 'symbol' | 'quantity' | 'price' | 'date' | 'type';
+export interface Account {
+    id: string;
+    name: string;
+    accountType: AccountType;
+    group?: string;
+    balance: number;
+    currency: string;
+    isDefault: boolean;
+    isActive: boolean;
+    isArchived: boolean;
+    trackingMode: 'TRANSACTIONS' | 'HOLDINGS' | 'NOT_SET';
+    createdAt: Date;
+    updatedAt: Date;
+    platformId?: string;
+    accountNumber?: string;
+    meta?: string;
+    provider?: string;
+    providerAccountId?: string;
+}
+/**
+ * Activity interface matching the v3 backend model
+ */
+export interface Activity {
+    id: string;
+    accountId: string;
+    assetId?: string;
+    activityType: string;
+    activityTypeOverride?: string;
+    sourceType?: string;
+    subtype?: string;
+    status: ActivityStatus;
+    activityDate: string;
+    settlementDate?: string;
+    quantity?: string;
+    unitPrice?: string;
+    amount?: string;
+    fee?: string;
+    currency: string;
+    fxRate?: string;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+    sourceSystem?: string;
+    sourceRecordId?: string;
+    sourceGroupId?: string;
+    idempotencyKey?: string;
+    importRunId?: string;
+    isUserModified: boolean;
+    needsReview: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Helper to get effective type (respects user override)
+ */
+export declare function getEffectiveType(activity: Activity): string;
+/**
+ * Check if activity has user override
+ */
+export declare function hasUserOverride(activity: Activity): boolean;
+export interface ActivityDetails {
+    id: string;
+    activityType: ActivityType;
+    subtype?: string | null;
+    status?: ActivityStatus;
+    date: Date;
+    quantity: string | null;
+    unitPrice: string | null;
+    amount: string | null;
+    fee: string | null;
+    currency: string;
+    needsReview: boolean;
+    comment?: string;
+    fxRate?: string | null;
+    createdAt: Date;
+    assetId: string;
+    updatedAt: Date;
+    accountId: string;
+    accountName: string;
+    accountCurrency: string;
+    assetSymbol: string;
+    assetName?: string;
+    assetQuoteMode?: QuoteMode;
+    exchangeMic?: string;
+    sourceSystem?: string;
+    sourceRecordId?: string;
+    idempotencyKey?: string;
+    importRunId?: string;
+    isUserModified?: boolean;
+    metadata?: Record<string, unknown>;
+    subRows?: ActivityDetails[];
+}
+export interface ActivitySearchResponse {
+    data: ActivityDetails[];
+    meta: {
+        totalRowCount: number;
+    };
+}
+export interface SymbolInput {
+    id?: string;
+    symbol?: string;
+    exchangeMic?: string;
+    kind?: string;
+    name?: string;
+    quoteMode?: QuoteMode;
+}
+export interface ActivityCreate {
+    id?: string;
+    accountId: string;
+    activityType: string;
+    subtype?: string | null;
+    activityDate: string | Date;
+    sourceGroupId?: string;
+    symbol?: SymbolInput;
+    quantity?: string | number | null;
+    unitPrice?: string | number | null;
+    amount?: string | number | null;
+    currency?: string;
+    fee?: string | number | null;
+    comment?: string | null;
+    fxRate?: string | number | null;
+    metadata?: string | Record<string, unknown>;
+}
+export interface ActivityUpdate {
+    id: string;
+    accountId: string;
+    activityType: string;
+    subtype?: string | null;
+    activityDate: string | Date;
+    sourceGroupId?: string;
+    symbol?: SymbolInput;
+    quantity?: string | number | null;
+    unitPrice?: string | number | null;
+    amount?: string | number | null;
+    currency?: string;
+    fee?: string | number | null;
+    comment?: string | null;
+    fxRate?: string | number | null;
+    metadata?: string | Record<string, unknown>;
+}
+export interface ActivityBulkMutationRequest {
+    creates?: ActivityCreate[];
+    updates?: ActivityUpdate[];
+    deleteIds?: string[];
+}
+export interface ActivityBulkMutationError {
+    id?: string;
+    action: string;
+    message: string;
+}
+export interface ActivityBulkIdentifierMapping {
+    tempId?: string | null;
+    activityId: string;
+}
+export interface ActivityBulkMutationResult {
+    created: Activity[];
+    updated: Activity[];
+    deleted: Activity[];
+    createdMappings: ActivityBulkIdentifierMapping[];
+    errors: ActivityBulkMutationError[];
+}
+export interface ActivityImport {
+    id?: string;
+    accountId: string;
+    currency?: string;
+    activityType: ActivityType;
+    subtype?: string;
+    date?: Date | string;
+    symbol: string;
+    amount?: number;
+    quantity?: number;
+    unitPrice?: number;
+    fee?: number;
+    fxRate?: number;
+    accountName?: string;
+    symbolName?: string;
+    /** Resolved exchange MIC for the symbol (populated during validation) */
+    exchangeMic?: string;
+    errors?: Record<string, string[]>;
+    isValid: boolean;
+    lineNumber?: number;
+    isDraft: boolean;
+    comment?: string;
+}
+export interface ImportActivitiesSummary {
+    total: number;
+    imported: number;
+    skipped: number;
+    duplicates: number;
+    assetsCreated: number;
+    success: boolean;
+}
+export interface ImportActivitiesResult {
+    activities: ActivityImport[];
+    importRunId: string;
+    summary: ImportActivitiesSummary;
+}
+export interface ImportMappingData {
+    accountId: string;
+    fieldMappings: Record<string, string>;
+    activityMappings: Record<string, string[]>;
+    symbolMappings: Record<string, string>;
+    accountMappings: Record<string, string>;
+}
+export interface SymbolSearchResult {
+    exchange: string;
+    /** Canonical exchange MIC code (e.g., "XNAS", "XTSE") */
+    exchangeMic?: string;
+    /** Friendly exchange name (e.g., "NASDAQ" instead of "NMS" or "XNAS") */
+    exchangeName?: string;
+    /** Currency derived from exchange (e.g., "USD", "CAD") */
+    currency?: string;
+    shortName: string;
+    quoteType: string;
+    symbol: string;
+    index: string;
+    score: number;
+    typeDisplay: string;
+    longName: string;
+    dataSource?: string;
+    /** Asset kind for custom assets (e.g., "INVESTMENT", "OTHER") */
+    assetKind?: string;
+    /** True if this asset already exists in user's database */
+    isExisting?: boolean;
+    /** The existing asset ID if found */
+    existingAssetId?: string;
+}
+export interface MarketDataProviderInfo {
+    id: string;
+    name: string;
+    logoFilename: string;
+    lastSyncedDate: string | null;
+}
+export interface Tag {
+    id: string;
+    name: string;
+    activityId: string | null;
+}
+export interface ImportValidationResult {
+    activities: ActivityImport[];
+    validationSummary: {
+        totalRows: number;
+        validCount: number;
+        invalidCount: number;
+    };
+}
+export type ValidationResult = {
+    status: 'success';
+} | {
+    status: 'error';
+    errors: string[];
+};
+export interface Instrument {
+    id: string;
+    symbol: string;
+    name?: string | null;
+    currency: string;
+    notes?: string | null;
+    quoteMode: QuoteMode;
+    preferredProvider?: string | null;
+    classifications?: AssetClassifications | null;
+}
+export interface AssetClassifications {
+    assetType?: TaxonomyCategory | null;
+    riskCategory?: TaxonomyCategory | null;
+    assetClasses: CategoryWithWeight[];
+    sectors: CategoryWithWeight[];
+    regions: CategoryWithWeight[];
+    customGroups: CategoryWithWeight[];
+}
+export interface TaxonomyCategory {
+    id: string;
+    taxonomyId: string;
+    parentId?: string | null;
+    name: string;
+    key: string;
+    color: string;
+    description?: string | null;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CategoryRef {
+    id: string;
+    name: string;
+}
+export interface CategoryWithWeight {
+    category: TaxonomyCategory;
+    topLevelCategory: CategoryRef;
+    weight: number;
+}
+export interface MonetaryValue {
+    local: number;
+    base: number;
+}
+export interface Lot {
+    id: string;
+    positionId: string;
+    acquisitionDate: string;
+    quantity: number;
+    costBasis: number;
+    acquisitionPrice: number;
+    acquisitionFees: number;
+}
+export interface Position {
+    id: string;
+    accountId: string;
+    assetId: string;
+    quantity: number;
+    averageCost: number;
+    totalCostBasis: number;
+    currency: string;
+    inceptionDate: string;
+    lots: Lot[];
+}
+export interface CashHolding {
+    id: string;
+    accountId: string;
+    currency: string;
+    amount: number;
+    lastUpdated: string;
+}
+export interface Holding {
+    id: string;
+    holdingType: HoldingType;
+    accountId: string;
+    instrument?: Instrument | null;
+    assetKind?: AssetKind | null;
+    quantity: number;
+    openDate?: string | Date | null;
+    lots?: Lot[] | null;
+    localCurrency: string;
+    baseCurrency: string;
+    fxRate?: number | null;
+    marketValue: MonetaryValue;
+    costBasis?: MonetaryValue | null;
+    price?: number | null;
+    unrealizedGain?: MonetaryValue | null;
+    unrealizedGainPct?: number | null;
+    realizedGain?: MonetaryValue | null;
+    realizedGainPct?: number | null;
+    totalGain?: MonetaryValue | null;
+    totalGainPct?: number | null;
+    dayChange?: MonetaryValue | null;
+    dayChangePct?: number | null;
+    prevCloseValue?: MonetaryValue | null;
+    weight: number;
+    asOfDate: string;
+}
+/**
+ * Asset interface matching the v3 backend model.
+ * Identity is opaque (UUID). Classification is via `kind` and `instrumentType`.
+ */
+export interface Asset {
+    id: string;
+    kind: AssetKind;
+    name?: string | null;
+    displayCode?: string | null;
+    notes?: string | null;
+    metadata?: Record<string, unknown>;
+    isActive?: boolean;
+    quoteMode: QuoteMode;
+    quoteCcy: string;
+    instrumentType?: string | null;
+    instrumentSymbol?: string | null;
+    instrumentExchangeMic?: string | null;
+    instrumentKey?: string | null;
+    providerConfig?: Record<string, unknown> | null;
+    exchangeName?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Quote {
+    id: string;
+    createdAt: string;
+    dataSource: string;
+    timestamp: string;
+    assetId: string;
+    open: number;
+    high: number;
+    low: number;
+    volume: number;
+    close: number;
+    adjclose: number;
+    currency: string;
+    notes?: string | null;
+}
+export interface QuoteUpdate {
+    timestamp: string;
+    assetId: string;
+    open: number;
+    high: number;
+    low: number;
+    volume: number;
+    close: number;
+    dataSource: string;
+}
+export interface Settings {
+    theme: string;
+    font: string;
+    baseCurrency: string;
+    instanceId: string;
+    onboardingCompleted: boolean;
+    autoUpdateCheckEnabled: boolean;
+    menuBarVisible: boolean;
+    syncEnabled: boolean;
+}
+export interface Goal {
+    id: string;
+    title: string;
+    description?: string;
+    targetAmount: number;
+    isAchieved?: boolean;
+    allocations?: GoalAllocation[];
+}
+export interface GoalAllocation {
+    id: string;
+    goalId: string;
+    accountId: string;
+    percentAllocation: number;
+}
+export interface GoalProgress {
+    name: string;
+    targetValue: number;
+    currentValue: number;
+    progress: number;
+    currency: string;
+}
+export interface IncomeByAsset {
+    assetId: string;
+    kind: AssetKind;
+    symbol: string;
+    name: string;
+    income: number;
+}
+export interface IncomeSummary {
+    period: string;
+    byMonth: Record<string, number>;
+    byType: Record<string, number>;
+    byAsset: Record<string, IncomeByAsset>;
+    byCurrency: Record<string, number>;
+    totalIncome: number;
+    currency: string;
+    monthlyAverage: number;
+    yoyGrowth: number | null;
+}
+export interface DateRange {
+    from: Date | undefined;
+    to: Date | undefined;
+}
+export type TimePeriod = '1D' | '1W' | '1M' | '3M' | '6M' | 'YTD' | '1Y' | '5Y' | 'ALL';
+export interface AccountValuation {
+    id: string;
+    accountId: string;
+    valuationDate: string;
+    accountCurrency: string;
+    baseCurrency: string;
+    fxRateToBase: number;
+    cashBalance: number;
+    investmentMarketValue: number;
+    totalValue: number;
+    costBasis: number;
+    netContribution: number;
+    calculatedAt: string;
+}
+export interface AccountSummaryView {
+    accountId: string;
+    accountName: string;
+    accountType: string;
+    accountGroup: string | null;
+    accountCurrency: string;
+    totalValueAccountCurrency: number;
+    totalValueBaseCurrency: number;
+    baseCurrency: string;
+    performance: SimplePerformanceMetrics;
+}
+export interface SimplePerformanceMetrics {
+    accountId: string;
+    totalValue?: number | null;
+    accountCurrency?: string | null;
+    baseCurrency?: string | null;
+    fxRateToBase?: number | null;
+    totalGainLossAmount?: number | null;
+    cumulativeReturnPercent?: number | null;
+    dayGainLossAmount?: number | null;
+    dayReturnPercentModDietz?: number | null;
+    portfolioWeight?: number | null;
+}
+export interface AccountGroup {
+    groupName: string;
+    accounts: AccountSummaryView[];
+    totalValueBaseCurrency: number;
+    baseCurrency: string;
+    performance: SimplePerformanceMetrics;
+    accountCount: number;
+}
+export interface ExchangeRate {
+    id: string;
+    fromCurrency: string;
+    toCurrency: string;
+    fromCurrencyName?: string;
+    toCurrencyName?: string;
+    rate: number;
+    source: string;
+    isLoading?: boolean;
+    timestamp: string;
+}
+export interface ContributionLimit {
+    id: string;
+    groupName: string;
+    contributionYear: number;
+    limitAmount: number;
+    accountIds?: string | null;
+    startDate?: string | null;
+    endDate?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export type NewContributionLimit = Omit<ContributionLimit, 'id' | 'createdAt' | 'updatedAt'>;
+export interface AccountDeposit {
+    amount: number;
+    currency: string;
+    convertedAmount: number;
+}
+export interface DepositsCalculation {
+    total: number;
+    baseCurrency: string;
+    byAccount: Record<string, AccountDeposit>;
+}
+export declare const ACTIVITY_TYPE_PREFIX_LENGTH = 12;
+export interface ReturnData {
+    date: string;
+    value: number;
+}
+export interface PerformanceMetrics {
+    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) */
+    periodReturn: number;
+    /** 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) */
+    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;
+}
+export interface UpdateAssetProfile {
+    id: string;
+    displayCode?: string | null;
+    name?: string | null;
+    notes?: string | null;
+    kind?: AssetKind | null;
+    quoteMode?: QuoteMode | null;
+    providerConfig?: Record<string, unknown> | null;
+}
+export interface TrackedItem {
+    id: string;
+    type: 'account' | 'symbol';
+    name: string;
+}
+export type ImportRunType = 'SYNC' | 'IMPORT';
+export type ImportRunMode = 'INITIAL' | 'INCREMENTAL' | 'BACKFILL' | 'REPAIR';
+export type ImportRunStatus = 'RUNNING' | 'APPLIED' | 'NEEDS_REVIEW' | 'FAILED' | 'CANCELLED';
+export type ReviewMode = 'NEVER' | 'ALWAYS' | 'IF_WARNINGS';
+export interface ImportRunSummary {
+    fetched: number;
+    inserted: number;
+    updated: number;
+    skipped: number;
+    warnings: number;
+    errors: number;
+    removed: number;
+}
+export interface ImportRun {
+    id: string;
+    accountId: string;
+    sourceSystem: string;
+    runType: ImportRunType;
+    mode: ImportRunMode;
+    status: ImportRunStatus;
+    startedAt: string;
+    finishedAt?: string;
+    reviewMode: ReviewMode;
+    appliedAt?: string;
+    checkpointIn?: Record<string, unknown>;
+    checkpointOut?: Record<string, unknown>;
+    summary?: ImportRunSummary;
+    warnings?: string[];
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export type SyncStatus = 'IDLE' | 'RUNNING' | 'NEEDS_REVIEW' | 'FAILED';
+export interface BrokerSyncState {
+    accountId: string;
+    provider: string;
+    checkpointJson?: Record<string, unknown>;
+    lastAttemptedAt?: string;
+    lastSuccessfulAt?: string;
+    lastError?: string;
+    lastRunId?: string;
+    syncStatus: SyncStatus;
+    createdAt: string;
+    updatedAt: string;
+}

package/dist/src/goal-progress.d.ts

@@ -0,0 +1,7 @@
+import type { Goal, GoalAllocation, AccountValuation, GoalProgress } from './data-types';
+/**
+ * Calculate goal progress using allocations.
+ * Converts account values to base currency, applies percent allocation per account,
+ * and computes progress ratio (0–1+) against target amount.
+ */
+export declare function calculateGoalProgress(accountsValuations: AccountValuation[], goals: Goal[], allocations: GoalAllocation[]): GoalProgress[];