@gala-chain/launchpad-sdk 3.15.2 → 3.15.4

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 3.15.4
+
+### Patch Changes
+
+- docs: comprehensive documentation updates for price history methods
+
+  ### SDK Documentation Updates
+  - Added complete documentation for all 4 price history methods in README.md
+    - fetchPriceHistory (paginated)
+    - fetchAllPriceHistory (auto-paginated)
+    - fetchPrices (paginated latest prices)
+    - fetchAllPrices (auto-paginated latest prices)
+  - Added comprehensive examples showing usage patterns, configuration, and workflows
+  - Updated MySQL configuration section with code examples for all 4 methods
+  - Added price history patterns documentation to CLAUDE.md
+  - Added latest token price queries section to CLAUDE.md with detailed examples
+  - Created comprehensive fetch-all-price-history-demo.ts example script
+    - Demonstrates statistical analysis, trend calculation, moving averages
+    - Shows CSV export, time period comparison, and multi-token analysis
+    - Includes volatility calculation and price statistics
+
+  ### MCP Server Documentation Updates
+  - Updated tool count from 52 to 55 in README (includes 4 price history tools)
+  - Added "Price History & Analysis" section documenting 4 price history tools
+  - Updated MCP installation version references (1.12.3, SDK 3.15.3)
+  - Added complete price history tool descriptions with use cases and examples
+
+  ### Agent Documentation Updates
+  - Updated @agent-galachain-launchpad-developer.md
+    - Updated SDK method count: 46 → 50 (includes price history)
+    - Updated MCP tool count: 51 → 55 (includes 4 price history tools)
+    - Updated version references: v3.11.0+ → v3.15.3+
+    - Added "Price History & Analysis" section to Complete Method Reference
+    - Updated service architecture to include PriceHistoryService
+    - Updated support section with latest version information
+
+## 3.15.3
+
+### Patch Changes
+
+- Fix: Initialize connection pool in fetchPrices method
+
+  fetchPrices was using this.pool! without calling ensureConnection first, causing a "Cannot read
+  properties of null" error. Now properly initializes the connection pool before querying.
+
 ## 3.15.2
 
 ### Patch Changes

package/README.md

@@ -793,6 +793,30 @@ calculateSellAmountExternal(options): Promise<AmountCalculationResult>
 // Explicit external calculation wrapper (same as calculateSellAmount)
 
 // Note: Pass `calculateAmountMode: 'local' | 'external'` to override SDK default mode
+
+// Price History Operations (MySQL-based, Node.js only)
+fetchPriceHistory(options): Promise<PriceHistoryResult>
+// Options: { tokenId, from?, to?, sortOrder?, page?, limit? }
+// Returns: { snapshots, page, limit, total, totalPages, hasNext, hasPrevious }
+// Fetches paginated historical price snapshots from MySQL database
+
+fetchAllPriceHistory(options): Promise<PriceHistoryResult>
+// Options: { tokenId, from?, to?, sortOrder? } (no pagination params)
+// Returns: All matching snapshots with total count
+// Convenience method with automatic pagination (returns ALL snapshots)
+
+fetchPrices(options?): Promise<PricesResult>
+// Options: { page?, limit?, sortByType? }
+// Returns: { snapshots, page, limit, total, totalPages, hasNext, hasPrevious }
+// Fetches latest price for each unique token (paginated)
+
+fetchAllPrices(): Promise<PricesResult>
+// No parameters
+// Returns: All latest prices combined in single result
+// Convenience method with automatic pagination (returns ALL latest prices)
+
+// Note: Price history methods require MySQL connection string in SDK config
+// See MySQL Configuration section below for setup details
 ```
 
 ## Performance Optimization
@@ -1353,7 +1377,7 @@ interface LaunchpadSDKConfig {
 
 ### MySQL Configuration (Price History)
 
-To use the `fetchPriceHistory()` method, you need to configure a MySQL connection string:
+To use the price history methods, you need to configure a MySQL connection string:
 
 ```typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
@@ -1366,22 +1390,60 @@ const sdk = createLaunchpadSDK({
   }
 });
 
-// Now you can fetch price history
+// 1. Fetch historical price snapshots (paginated)
 const priceHistory = await sdk.fetchPriceHistory({
-  tokenClassKey: {
+  tokenId: 'Token|Unit|GUSDC|eth:9401b171307bE656f00F9e18DF756643FD3a91dE', // String format
+  from: new Date('2024-01-01'),
+  to: new Date('2024-01-31'),
+  sortOrder: 'DESC',
+  page: 1,
+  limit: 20
+});
+
+console.log(`Found ${priceHistory.snapshots.length} snapshots`);
+console.log(`Total: ${priceHistory.total}, Page ${priceHistory.page} of ${priceHistory.totalPages}`);
+
+// 2. Fetch ALL historical price snapshots (auto-paginated)
+const allHistory = await sdk.fetchAllPriceHistory({
+  tokenId: { // Object format also supported
     collection: 'Token',
     category: 'Unit',
     type: 'GUSDC',
     additionalKey: 'eth:9401b171307bE656f00F9e18DF756643FD3a91dE'
   },
   from: new Date('2024-01-01'),
-  to: new Date('2024-01-31'),
+  to: new Date('2024-01-31')
+});
+
+console.log(`Total snapshots: ${allHistory.total}`);
+
+// 3. Fetch latest prices for all tokens (paginated)
+const latestPrices = await sdk.fetchPrices({
   page: 1,
-  limit: 20
+  limit: 20,
+  sortByType: 'ASC' // Optional: sort alphabetically by token type
 });
 
-console.log(`Found ${priceHistory.snapshots.length} snapshots`);
-console.log(`Total: ${priceHistory.total}, Page ${priceHistory.page} of ${priceHistory.totalPages}`);
+console.log(`Found ${latestPrices.snapshots.length} tokens with prices`);
+
+// 4. Fetch all latest prices (auto-paginated)
+const allLatestPrices = await sdk.fetchAllPrices();
+
+console.log(`Total tokens with prices: ${allLatestPrices.total}`);
+```
+
+**Token Identification Formats:**
+```typescript
+// String format (pipe-delimited) - simpler
+tokenId: 'Token|Unit|GUSDC|eth:9401b171307bE656f00F9e18DF756643FD3a91dE'
+
+// Object format (explicit) - for clarity
+tokenId: {
+  collection: 'Token',
+  category: 'Unit',
+  type: 'GUSDC',
+  additionalKey: 'eth:9401b171307bE656f00F9e18DF756643FD3a91dE'
+}
 ```
 
 **Environment Configuration:**

package/dist/constants/version.generated.d.ts

@@ -3,5 +3,5 @@
  * This file is generated by scripts/inject-version.ts during build
  * DO NOT EDIT MANUALLY
  */
-export declare const SDK_VERSION = "3.15.2";
+export declare const SDK_VERSION = "3.15.4";
 //# sourceMappingURL=version.generated.d.ts.map