{"_id":"@cygnus-wealth/robinhood-integration","name":"@cygnus-wealth/robinhood-integration","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cygnus-wealth/robinhood-integration","version":"0.1.0","description":"Robinhood API integration library for CygnusWealth - standardized portfolio data extraction","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest","test:ui":"vitest --ui","test:coverage":"vitest --coverage","lint":"eslint src --ext .ts","format":"prettier --write \"src/**/*.ts\"","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["robinhood","api","portfolio","finance","crypto","stocks","integration"],"author":{"name":"CygnusWealth"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Cygnus-Wealth/robinhood-integration.git"},"publishConfig":{"access":"public"},"bugs":{"url":"https://github.com/Cygnus-Wealth/robinhood-integration/issues"},"homepage":"https://github.com/Cygnus-Wealth/robinhood-integration#readme","dependencies":{"axios":"^1.7.2","uuid":"^9.0.1"},"devDependencies":{"@types/node":"^20.14.9","@types/uuid":"^9.0.8","@typescript-eslint/eslint-plugin":"^7.14.1","@typescript-eslint/parser":"^7.14.1","@vitest/coverage-v8":"^1.6.1","@vitest/ui":"^1.6.0","eslint":"^8.57.0","prettier":"^3.3.2","typescript":"^5.5.2","vitest":"^1.6.0"},"peerDependencies":{"@cygnus-wealth/data-models":"*"},"engines":{"node":">=18.0.0"},"gitHead":"45a899d1fdd9bb95e373e1f9c793aec6476cdea7","_id":"@cygnus-wealth/robinhood-integration@0.1.0","_nodeVersion":"22.22.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-0r9F/AtFOZN9ivjEv+X+r5KXbBZsaiTqO5sFZk/XaMcQqkHZV6T5RdFoQafUQpGO+adxW3mLny6FpRAXYi9vWw==","shasum":"ad3d899ee3f3097ceb7eb293ecf8012db4d92f64","tarball":"https://registry.npmjs.org/@cygnus-wealth/robinhood-integration/-/robinhood-integration-0.1.0.tgz","fileCount":65,"unpackedSize":243256,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFvpDZYBedGvYqGfp5AlG/D2u7eyTXEvVWV/o8VWmqFyAiEApa7TdU+WRsIre1+x1ESiSAPmQKOtau/0wD6n+KBEtvw="}]},"_npmUser":{"name":"linuxninja39","email":"jacob@s56.net"},"directories":{},"maintainers":[{"name":"linuxninja39","email":"jacob@s56.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/robinhood-integration_0.1.0_1771039305024_0.2978742730712214"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-14T03:21:44.879Z","0.1.0":"2026-02-14T03:21:45.191Z","modified":"2026-02-14T03:21:45.476Z"},"maintainers":[{"name":"linuxninja39","email":"jacob@s56.net"}],"description":"Robinhood API integration library for CygnusWealth - standardized portfolio data extraction","homepage":"https://github.com/Cygnus-Wealth/robinhood-integration#readme","keywords":["robinhood","api","portfolio","finance","crypto","stocks","integration"],"repository":{"type":"git","url":"git+https://github.com/Cygnus-Wealth/robinhood-integration.git"},"author":{"name":"CygnusWealth"},"bugs":{"url":"https://github.com/Cygnus-Wealth/robinhood-integration/issues"},"license":"MIT","readme":"# @cygnus-wealth/robinhood-integration\n\nA TypeScript library for integrating with Robinhood's API to fetch portfolio data with standardized outputs compatible with @cygnus-wealth/data-models interfaces.\n\n## Overview\n\nThis library provides a clean, type-safe interface for accessing Robinhood portfolio data. It handles authentication, API requests, and data transformation to standardized models for seamless integration with the CygnusWealth platform.\n\n## Features\n\n- **Read-only Access**: Secure, read-only integration with Robinhood accounts\n- **Standardized Data Models**: Outputs conform to @cygnus-wealth/data-models interfaces\n- **Type Safety**: Full TypeScript support with comprehensive type definitions\n- **Error Handling**: Robust error handling with standardized error responses\n- **Data Mapping**: Automatic conversion from Robinhood's API format to standardized models\n- **Portfolio Management**: Access to positions, balances, quotes, transactions, and more\n- **Historical Data**: Fetch historical price data for analysis\n- **Real-time Quotes**: Get current market prices and quote information\n\n## Installation\n\n```bash\nnpm install @cygnus-wealth/robinhood-integration\n```\n\n## Usage\n\n### Basic Setup\n\n```typescript\nimport { RobinhoodService } from '@cygnus-wealth/robinhood-integration';\n\nconst robinhood = new RobinhoodService({\n  timeout: 30000,\n  retryAttempts: 3,\n});\n```\n\n### Authentication\n\n```typescript\n// Authenticate with credentials\nawait robinhood.authenticate({\n  username: 'your-username',\n  password: 'your-password',\n  mfaCode: '123456', // Optional: for MFA\n});\n\n// Check authentication status\nif (robinhood.isAuthenticated()) {\n  console.log('Successfully authenticated');\n}\n```\n\n### Fetching Portfolio Data\n\n```typescript\n// Get complete portfolio overview\nconst portfolio = await robinhood.getPortfolio();\nconsole.log(`Total Value: $${portfolio.totalValue}`);\nconsole.log(`Day Change: ${portfolio.dayChangePercent}%`);\n\n// Get all positions\nconst positions = await robinhood.getPositions();\npositions.forEach(position => {\n  console.log(`${position.symbol}: ${position.quantity} shares @ $${position.currentPrice}`);\n});\n\n// Get specific position\nconst position = await robinhood.getPosition('AAPL');\nif (position) {\n  console.log(`AAPL Market Value: $${position.marketValue}`);\n}\n```\n\n### Account Information\n\n```typescript\n// Get account details\nconst accounts = await robinhood.getAccounts();\naccounts.forEach(account => {\n  console.log(`Account ${account.accountNumber}: ${account.type}`);\n});\n\n// Get account balance\nconst balance = await robinhood.getBalance();\nconsole.log(`Cash Balance: $${balance.cashBalance}`);\nconsole.log(`Buying Power: $${balance.buyingPower}`);\n```\n\n### Market Data\n\n```typescript\n// Get single quote\nconst quote = await robinhood.getQuote('TSLA');\nconsole.log(`TSLA Price: $${quote.price}`);\nconsole.log(`Change: ${quote.changePercent}%`);\n\n// Get multiple quotes\nconst quotes = await robinhood.getQuotes(['AAPL', 'GOOGL', 'MSFT']);\nquotes.forEach(quote => {\n  console.log(`${quote.symbol}: $${quote.price}`);\n});\n\n// Get historical data\nconst historicals = await robinhood.getHistoricalData('SPY', 'day', 'month');\nhistoricals.data.forEach(point => {\n  console.log(`${point.timestamp}: $${point.close}`);\n});\n```\n\n### Transaction History\n\n```typescript\n// Get recent transactions\nconst transactions = await robinhood.getTransactions(50);\ntransactions.forEach(tx => {\n  console.log(`${tx.type} ${tx.quantity} ${tx.symbol} @ $${tx.price}`);\n});\n\n// Get dividends\nconst dividends = await robinhood.getDividends();\ndividends.forEach(div => {\n  console.log(`${div.symbol}: $${div.amount} on ${div.paymentDate}`);\n});\n```\n\n### Watchlists\n\n```typescript\n// Get all watchlists\nconst watchlists = await robinhood.getWatchlists();\nwatchlists.forEach(list => {\n  console.log(`${list.name}: ${list.symbols.join(', ')}`);\n});\n```\n\n## API Reference\n\n### RobinhoodService\n\nThe main service class for interacting with Robinhood.\n\n#### Methods\n\n- `authenticate(credentials: RobinhoodCredentials): Promise<void>`\n- `refreshToken(): Promise<void>`\n- `isAuthenticated(): boolean`\n- `getPortfolio(): Promise<StandardizedPortfolio>`\n- `getPositions(): Promise<StandardizedPosition[]>`\n- `getPosition(symbol: string): Promise<StandardizedPosition | null>`\n- `getAccounts(): Promise<StandardizedAccount[]>`\n- `getBalance(): Promise<StandardizedBalance>`\n- `getQuote(symbol: string): Promise<StandardizedQuote>`\n- `getQuotes(symbols: string[]): Promise<StandardizedQuote[]>`\n- `getTransactions(limit?: number): Promise<StandardizedTransaction[]>`\n- `getHistoricalData(symbol: string, interval?: string, span?: string): Promise<StandardizedHistoricalData>`\n- `getWatchlists(): Promise<StandardizedWatchlist[]>`\n- `getDividends(): Promise<StandardizedDividend[]>`\n\n## Data Models\n\nAll output data conforms to standardized interfaces for easy integration:\n\n- `StandardizedPortfolio`: Complete portfolio overview\n- `StandardizedPosition`: Individual position details\n- `StandardizedTransaction`: Transaction/order information\n- `StandardizedBalance`: Account balance details\n- `StandardizedQuote`: Market quote data\n- `StandardizedHistoricalData`: Historical price data\n- `StandardizedAccount`: Account information\n- `StandardizedWatchlist`: Watchlist data\n- `StandardizedDividend`: Dividend payment information\n\n## Error Handling\n\nThe library provides standardized error responses:\n\n```typescript\ntry {\n  const portfolio = await robinhood.getPortfolio();\n} catch (error) {\n  if (error.code === 'AUTH_FAILED') {\n    // Handle authentication failure\n  } else if (error.code === 'PORTFOLIO_FETCH_FAILED') {\n    // Handle portfolio fetch failure\n  }\n  console.error(`Error: ${error.message}`);\n}\n```\n\n## Security Considerations\n\n- **Client-side Only**: This library is designed for client-side use in the CygnusWealth dApp\n- **No Private Keys**: Never handles private keys or transaction signing\n- **Read-only Access**: Only provides read access to account data\n- **Token Management**: Handles token refresh automatically\n- **Secure Storage**: Tokens should be encrypted when stored locally\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the library\nnpm run build\n\n# Run tests\nnpm test\n\n# Run linting\nnpm run lint\n\n# Type checking\nnpm run typecheck\n```\n\n## Suggestions for @cygnus-wealth/data-models\n\nBased on the Robinhood integration implementation, here are some suggestions for the data-models library:\n\n1. **Additional Asset Types**: Consider adding support for options and forex in the position types\n2. **Extended Quote Data**: Add fields for extended hours trading, market cap, P/E ratio, and dividend yield\n3. **Order Types**: Expand transaction types to include limit orders, stop orders, and options transactions\n4. **Crypto Support**: Add specific interfaces for cryptocurrency holdings and quotes\n5. **Tax Information**: Consider adding interfaces for tax lots and cost basis information\n6. **Performance Metrics**: Add interfaces for performance calculations (Sharpe ratio, alpha, beta)\n7. **Notifications**: Standardized interface for price alerts and account notifications\n\n## Contributing\n\nContributions are welcome! Please follow the existing code style and add tests for new features.\n\n## License\n\nMIT\n\n## Support\n\nFor issues and feature requests, please use the GitHub issue tracker.\n","readmeFilename":"README.md","_rev":"1-1258704f6975bb24f793af5d5da614e7"}