feat: update ingestor and shared packages

[salazarsebas]

🚀 Neko Pull Request

Pull Request: Define Raw Price Data Model and Normalization

Issue Reference: #9
Branch: feat/define-raw-price-data-model-and-normalization

---

Overview

This pull request introduces a standardized RawPrice interface in the shared package and establishes a provider abstraction layer in the ingestor service. These changes ensure consistent data structures across all price data providers and improve maintainability for future integrations.

---

Motivation

Previously, the RawPrice interface was defined locally within the ingestor service, limiting reusability across other packages. Additionally, there was no abstraction layer for price data providers, making it difficult to add new data sources in a consistent manner.

This PR addresses these architectural gaps by:

• Centralizing type definitions in the shared package
• Creating a provider interface contract for all price data sources
• Ensuring type safety and consistency across the monorepo

---

Changes Summary

New Files

File Path	Description
packages/shared/src/types/raw-price.ts	Canonical RawPrice interface definition with JSDoc documentation
packages/shared/src/types/index.ts	Barrel file for type exports
apps/ingestor/src/providers/provider.interface.ts	PriceProvider interface defining the contract for all data providers
apps/ingestor/src/providers/mock.provider.ts	Mock provider implementation for development and testing
apps/ingestor/src/providers/index.ts	Barrel file for provider exports

Modified Files

File Path	Description
packages/shared/src/index.ts	Added type exports from the types directory
apps/ingestor/package.json	Added @oracle-stocks/shared as a dependency
apps/ingestor/src/services/price-fetcher.service.ts	Refactored to use shared types and provider abstraction
apps/ingestor/src/controllers/prices.controller.ts	Updated imports to use RawPrice from shared package

---

Technical Details

RawPrice Interface

The RawPrice interface serves as the canonical data structure for all ingested price data:

interface RawPrice {
  symbol: string;    // Stock ticker symbol (e.g., 'AAPL', 'GOOGL')
  price: number;     // Price value in USD
  timestamp: number; // Unix timestamp in milliseconds
  source: string;    // Data source identifier (e.g., 'AlphaVantage')
}

PriceProvider Interface

The PriceProvider interface establishes a contract for all price data providers:

interface PriceProvider {
  readonly name: string;
  fetchPrices(symbols: string[]): Promise<RawPrice[]>;
}

Architecture Diagram

+---------------------------+
|    @oracle-stocks/shared  |
|  +---------------------+  |
|  |     RawPrice        |  |
|  |     (interface)     |  |
|  +---------------------+  |
+------------+--------------+
             |
             | imports
             v
+---------------------------+
|  @oracle-stocks/ingestor  |
|  +---------------------+  |
|  |   PriceProvider     |  |
|  |   (interface)       |  |
|  +----------+----------+  |
|             |             |
|      implements           |
|             |             |
|  +----------v----------+  |
|  |   MockProvider      |  |
|  +---------------------+  |
|             |             |
|       used by             |
|             |             |
|  +----------v----------+  |
|  | PriceFetcherService |  |
|  +---------------------+  |
+---------------------------+

---

Breaking Changes

None. This is a backward-compatible refactoring that:

• Moves the existing RawPrice interface to a shared location
• Maintains the same data structure and field names
• Preserves existing API endpoint behavior

---

Testing

Build Verification

Package	Status
@oracle-stocks/shared	Passed
@oracle-stocks/ingestor	Passed
@oracle-stocks/api	Passed
@oracle-stocks/aggregator	Passed
@oracle-stocks/signer	Passed
@oracle-stocks/transactor	Passed
@oracle-stocks/frontend	Passed

Lint Verification

Package	Status
All packages	No warnings or errors

Manual Testing

To verify the implementation:

1. Start the ingestor service:

   npm run dev --workspace=apps/ingestor

2. Test the /prices/raw endpoint:

   curl http://localhost:3001/prices/raw

3. Verify the response conforms to the RawPrice schema:

   [
     {
       "symbol": "AAPL",
       "price": 150.25,
       "timestamp": 1705916400000,
       "source": "MockProvider"
     }
   ]

---

Checklist

• RawPrice interface defined and exported from shared types
• All ingestor outputs conform to RawPrice schema
• Normalized format consistent across providers
• Provider abstraction layer implemented
• Build passes for all packages
• Lint passes for all packages
• No breaking changes introduced

---

Future Considerations

This architecture enables straightforward integration of additional price providers:

1. AlphaVantage Provider - Real-time stock data
2. Yahoo Finance Provider - Market data and historical prices
3. Finnhub Provider - Real-time market data

Each new provider simply needs to implement the PriceProvider interface and register with the PriceFetcherService.

---

Reviewers

Please review the following areas:

Area	Focus Points
Type Definitions	Ensure RawPrice interface covers all necessary fields
Provider Interface	Validate the contract is flexible enough for real providers
Service Refactoring	Confirm the provider pattern is correctly implemented
Package Dependencies	Verify workspace dependency is properly configured

---

Related Issues

• Closes Define raw price data model and normalization #9

---

Thank you for contributing to Neko, you just helped us make RWAs consumer friendly on Stellar! We hope you can continue contributing to this project.

[FabianSanchezD]

LGTM!