{"_id":"@cygnus-wealth/portfolio-aggregation","_rev":"2-444e6a40e9f94258742cd94d5bf54fa7","name":"@cygnus-wealth/portfolio-aggregation","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@cygnus-wealth/portfolio-aggregation","version":"0.1.0","keywords":["domain:portfolio","context:aggregation","type:service-library","cygnus-wealth","ddd","portfolio-management","orchestration"],"author":{"name":"CygnusWealth"},"license":"MIT","_id":"@cygnus-wealth/portfolio-aggregation@0.1.0","maintainers":[{"name":"linuxninja39","email":"jacob@s56.net"}],"homepage":"https://github.com/cygnus-wealth/portfolio-aggregation#readme","bugs":{"url":"https://github.com/cygnus-wealth/portfolio-aggregation/issues"},"dist":{"shasum":"85d323fccda20b84710e9624ffc8d837e45b6d37","tarball":"https://registry.npmjs.org/@cygnus-wealth/portfolio-aggregation/-/portfolio-aggregation-0.1.0.tgz","fileCount":5,"integrity":"sha512-jL45XAvqYv5KGq16A9bZYn/wtE4c2AaR6F/6h5q65O3fwNiMVe/CLGR+ejLPY0y4C+sFmDGLeI8XD6V9O1bErg==","signatures":[{"sig":"MEQCIEuIN5uDewBT5ygLkS7yCby8YQrXdK3pbgTqwc/83vJoAiA2SSwJ4sEG62iUMkvWdYbZV0IbdFGHV8svGR0+lCj5dw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":263229},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"c95bb6bd01f43666e4bfcaa993ef7398ef4ab773","private":false,"scripts":{"lint":"eslint .","test":"vitest","build":"tsc -b && vite build --config vite.config.library.ts","clean":"rm -rf dist .turbo","format":"prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md}\"","test:ui":"vitest --ui","test:once":"vitest run","typecheck":"tsc --noEmit","build:types":"tsc --emitDeclarationOnly --declaration --declarationMap","test:coverage":"vitest --coverage","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"linuxninja39","email":"jacob@s56.net"},"repository":{"url":"git+https://github.com/Cygnus-Wealth/portfolio-aggregation.git","type":"git"},"_npmVersion":"11.7.0","description":"Portfolio orchestration and aggregation service library for CygnusWealth client applications","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@cygnus-wealth/data-models":"^1.0.0","@cygnus-wealth/asset-valuator":"^0.2.0","@cygnus-wealth/evm-integration":"^1.0.0","@cygnus-wealth/sol-integration":"^0.1.0","@cygnus-wealth/robinhood-integration":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^7.1.2","jsdom":"^26.1.0","eslint":"^9.33.0","vitest":"^3.2.4","globals":"^16.3.0","@eslint/js":"^9.33.0","typescript":"~5.8.3","@types/react":"^19.1.10","@types/react-dom":"^19.1.7","typescript-eslint":"^8.39.1","@vitejs/plugin-react":"^5.0.0","@testing-library/react":"^16.3.0","@testing-library/jest-dom":"^6.8.0","eslint-plugin-react-hooks":"^5.2.0","@testing-library/user-event":"^14.6.1","eslint-plugin-react-refresh":"^0.4.20"},"peerDependencies":{"events":"^3.3.0"},"_npmOperationalInternal":{"tmp":"tmp/portfolio-aggregation_0.1.0_1771049616014_0.39775547274761625","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@cygnus-wealth/portfolio-aggregation","private":false,"version":"0.2.0","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"description":"Portfolio orchestration and aggregation service library for CygnusWealth client applications","keywords":["domain:portfolio","context:aggregation","type:service-library","cygnus-wealth","ddd","portfolio-management","orchestration"],"repository":{"type":"git","url":"git+https://github.com/Cygnus-Wealth/portfolio-aggregation.git"},"publishConfig":{"access":"public"},"homepage":"https://github.com/cygnus-wealth/portfolio-aggregation#readme","bugs":{"url":"https://github.com/cygnus-wealth/portfolio-aggregation/issues"},"author":{"name":"CygnusWealth"},"license":"MIT","scripts":{"build":"tsc -b && vite build --config vite.config.library.ts","build:types":"tsc --emitDeclarationOnly --declaration --declarationMap","lint":"eslint .","test":"vitest","test:ui":"vitest --ui","test:coverage":"vitest --coverage","test:once":"vitest run","test:e2e":"vitest run --config vitest.e2e.config.ts","typecheck":"tsc --noEmit","clean":"rm -rf dist .turbo","format":"prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md}\"","prepublishOnly":"npm run clean && npm run build"},"dependencies":{"@cygnus-wealth/data-models":"^1.0.0","@cygnus-wealth/evm-integration":"^1.0.0","@cygnus-wealth/sol-integration":"^0.1.0","@cygnus-wealth/robinhood-integration":"^0.1.0","@cygnus-wealth/asset-valuator":"^0.2.0"},"peerDependencies":{"events":"^3.3.0"},"devDependencies":{"@eslint/js":"^9.33.0","@testing-library/jest-dom":"^6.8.0","@testing-library/react":"^16.3.0","@testing-library/user-event":"^14.6.1","@types/react":"^19.1.10","@types/react-dom":"^19.1.7","@vitejs/plugin-react":"^5.0.0","eslint":"^9.33.0","eslint-plugin-react-hooks":"^5.2.0","eslint-plugin-react-refresh":"^0.4.20","globals":"^16.3.0","jsdom":"^26.1.0","typescript":"~5.8.3","typescript-eslint":"^8.39.1","vite":"^7.1.2","vitest":"^3.2.4"},"gitHead":"b859613c6a89aca2f636d12dadc9bc1fc9cbb6eb","_id":"@cygnus-wealth/portfolio-aggregation@0.2.0","_nodeVersion":"20.20.0","_npmVersion":"11.10.0","dist":{"integrity":"sha512-a6xKBAhbFaul/E8CDbZQ9difzblBzr+Fr40r0Ka4/VNjLwc8G289PI/6J1kixIHLOayWhnP6C493uedi5h3uxg==","shasum":"4e6b4429f4c94ef080ba83e070b9a3fb779e7db1","tarball":"https://registry.npmjs.org/@cygnus-wealth/portfolio-aggregation/-/portfolio-aggregation-0.2.0.tgz","fileCount":5,"unpackedSize":267178,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cygnus-wealth%2fportfolio-aggregation@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDzyIiACwD/YebaWNdvaOkGtxkWpCy/wL+Y3jHoHkRnTQIhAIOn2mFTFlAXEloJIghyyTKPw/GBQG/HiQrSOPjuIqD2"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6033bf47-59c9-42ed-8c9b-dcc7d266a7c7"}},"directories":{},"maintainers":[{"name":"linuxninja39","email":"jacob@s56.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/portfolio-aggregation_0.2.0_1771350270180_0.26807528797539426"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-14T06:13:35.907Z","modified":"2026-02-17T17:44:30.598Z","0.1.0":"2026-02-14T06:13:36.165Z","0.2.0":"2026-02-17T17:44:30.313Z"},"bugs":{"url":"https://github.com/cygnus-wealth/portfolio-aggregation/issues"},"author":{"name":"CygnusWealth"},"license":"MIT","homepage":"https://github.com/cygnus-wealth/portfolio-aggregation#readme","keywords":["domain:portfolio","context:aggregation","type:service-library","cygnus-wealth","ddd","portfolio-management","orchestration"],"repository":{"type":"git","url":"git+https://github.com/Cygnus-Wealth/portfolio-aggregation.git"},"description":"Portfolio orchestration and aggregation service library for CygnusWealth client applications","maintainers":[{"name":"linuxninja39","email":"jacob@s56.net"}],"readme":"# Portfolio Aggregation Service Library\n\n**Domain**: Portfolio  \n**Bounded Context**: Orchestration and Aggregation  \n**Type**: Service Library (NPM Package)  \n**Package**: `@cygnus-wealth/portfolio-aggregation`\n\n## Overview\n\nThe Portfolio Aggregation service library is a reusable npm package that provides portfolio orchestration and aggregation capabilities for client applications. This library coordinates data collection from multiple integration packages and combines them into a unified portfolio view.\n\n**Key Characteristics**:\n- Service layer library, not a standalone application\n- No UI components (consumed by @cygnus-wealth/cygnus-wealth-core)\n- Orchestrates but doesn't implement integrations\n- Provides domain services and aggregates as reusable components\n- Emits domain events for consuming applications\n\n## Installation\n\n```bash\nnpm install @cygnus-wealth/portfolio-aggregation\n```\n\n## Library Architecture\n\nThis service library follows Domain-Driven Design (DDD) principles with the following structure:\n\n```\nsrc/\n├── domain/              # Core business logic\n│   ├── entities/       # Domain entities\n│   ├── value-objects/  # Value objects\n│   ├── aggregates/     # Domain aggregates\n│   └── services/       # Domain services\n├── application/        # Application layer\n│   ├── services/      # Application services (main exports)\n│   ├── use-cases/     # Use case implementations\n│   └── commands/      # Command handlers\n├── infrastructure/    # Infrastructure layer\n│   ├── repositories/  # Repository implementations\n│   ├── adapters/     # Integration adapters\n│   └── cache/        # Caching strategies\n├── contracts/        # Public interfaces and contracts\n├── shared/          # Shared utilities and types\n└── index.ts        # Public API exports\n```\n\n**Note**: This library has no presentation layer. UI components are implemented in consuming applications like @cygnus-wealth/cygnus-wealth-core.\n\n## Core Responsibilities\n\n1. **Data Orchestration**: Coordinates parallel data fetching from multiple integration domains\n2. **Portfolio Composition**: Combines assets from different sources into a unified portfolio\n3. **Deduplication**: Identifies and merges duplicate assets across sources\n4. **Reconciliation**: Handles discrepancies between different data sources\n5. **Caching Strategy**: Implements intelligent caching to minimize external API calls\n6. **Error Handling**: Provides graceful degradation when some sources are unavailable\n\n## Dependencies\n\n### Runtime Dependencies\n- `@cygnus-wealth/data-models` - Shared data contracts and unified structures\n- `@cygnus-wealth/evm-integration` - EVM blockchain integration\n- `@cygnus-wealth/sol-integration` - Solana blockchain integration  \n- `@cygnus-wealth/robinhood-integration` - Traditional finance integration\n- `@cygnus-wealth/asset-valuator` - Asset pricing and valuation services\n\n### Development Dependencies\n- TypeScript - Type safety and library definitions\n- Vite - Build tooling for library bundling\n- Vitest - Testing framework\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run development server\nnpm run dev\n\n# Run tests\nnpm run test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Type checking\nnpm run typecheck\n\n# Build for production\nnpm run build\n```\n\n## Testing\n\nThe project uses Vitest for testing with the following structure:\n\n- `src/tests/unit/` - Unit tests for domain logic\n- `src/tests/integration/` - Integration tests\n- `src/tests/e2e/` - End-to-end tests\n\nRun tests with:\n```bash\nnpm run test         # Run tests in watch mode\nnpm run test:once    # Run tests once\nnpm run test:coverage # Generate coverage report\n```\n\n## Library Usage\n\n### Installation in Client Applications\n\n```bash\nnpm install @cygnus-wealth/portfolio-aggregation\n```\n\n### Basic Integration\n\n```typescript\nimport { \n  PortfolioAggregationService,\n  IIntegrationRepository,\n  IPortfolioRepository,\n  IAssetValuatorRepository \n} from '@cygnus-wealth/portfolio-aggregation';\n\n// Client application provides implementations\nconst integrations: IIntegrationRepository[] = [\n  evmIntegration,\n  solanaIntegration,\n  robinhoodIntegration\n];\n\nconst portfolioRepository: IPortfolioRepository = // client's storage implementation\nconst assetValuator: IAssetValuatorRepository = // valuator service instance\n\n// Initialize the service\nconst service = new PortfolioAggregationService(\n  integrations,\n  portfolioRepository,\n  assetValuator\n);\n\n// Use the service to aggregate portfolio\nconst portfolio = await service.aggregatePortfolio({\n  sources: [IntegrationSource.EVM, IntegrationSource.SOLANA],\n  addresses: new Map([\n    ['ethereum', ['0x...']],\n    ['solana', ['...']],\n  ]),\n  userId: 'user123',\n  forceRefresh: false\n});\n```\n\n### Event Subscription\n\n```typescript\n// Subscribe to domain events\nservice.on('PortfolioAggregated', (event) => {\n  console.log('Portfolio aggregation completed', event);\n});\n\nservice.on('IntegrationSourceFailed', (event) => {\n  console.error('Integration failed', event.source, event.error);\n});\n```\n\n## Public API Exports\n\nThe library exports the following for use by consuming applications:\n\n### Services\n- `PortfolioAggregationService` - Main orchestration service\n- `ReconciliationService` - Asset deduplication and reconciliation\n\n### Interfaces\n- `IIntegrationRepository` - Interface for integration adapters\n- `IPortfolioRepository` - Portfolio persistence interface\n- `IAssetValuatorRepository` - Valuation service interface\n\n### Domain Models\n- `PortfolioAggregate` - Core portfolio aggregate\n- `AssetEntity` - Asset domain entity\n- `Money` - Value object for monetary values\n- `Address` - Value object for blockchain addresses\n\n### Event Types\n- Domain event interfaces and types\n- Event emitter integration\n\n## Integration with CygnusWealth Core\n\nThis library is primarily consumed by `@cygnus-wealth/cygnus-wealth-core`, which:\n- Provides the UI components and user interactions\n- Manages client-side state and browser storage\n- Handles user configuration and preferences\n- Instantiates and coordinates service library usage\n\n## Contributing\n\nWhen contributing to this service library:\n1. Maintain clear domain boundaries - this is orchestration only\n2. Don't add UI components - those belong in consuming applications\n3. Follow DDD principles for domain modeling\n4. Ensure all public API changes are backward compatible or properly versioned\n5. Add integration interfaces through the IIntegrationRepository pattern\n\n## License\n\nMIT","readmeFilename":"README.md"}