feat: improve component documentation and validation

- Add markdown formatting to all example values with backticks
- Highlight date formats (`YYYY-MM-DD`) in prop descriptions
- Add `min: 1` validation to all page props across 19 action files
- Remove verbose pagination descriptions in favor of built-in validation
- Standardize prop definitions using `propDefinitions` from app file
- Convert comma-separated string props to `string[]` type for better UX
- Remove redundant `if ($ && $.export)` checks from all actions
- Remove custom `try/catch` blocks to leverage Pipedream's native error handling
- Clean up `handleApiError` utility function and related imports
- Fix prop descriptions to use proper options instead of text descriptions
- Update README.md to be more concise and professional per feedback

This refactor improves code maintainability, user experience, and follows
Pipedream component best practices for validation, error handling, and
documentation formatting.

Author: HarshGautam7101

components/token_metrics/README.md

@@ -30,102 +30,17 @@ The API uses API key authentication via the `x-api-key` header. Your API key sho
 3. In Pipedream, connect the Token Metrics app using your API key
 4. The API key will be automatically included in all requests via the `x-api-key` header
 
-# Available Actions
-
-## Core Data Actions
-- **Get Tokens**: Retrieve comprehensive token listings with metadata and analytics
-- **Get Price**: Fetch current token prices for specified assets
-- **Get Top Market Cap Tokens**: Access tokens ranked by market capitalization
-
-## Trading & Signals
-- **Get Trading Signals**: AI-generated long/short trading signals for all tokens
-- **Get Hourly Trading Signals**: Real-time hourly trading signals
-- **Get Moonshot Tokens**: AI-curated high-potential token picks
-
-## Market Analysis
-- **Get Market Metrics**: Comprehensive crypto market analytics and sentiment indicators
-- **Get Correlation**: Token correlation analysis with top 100 market cap assets
-- **Get Scenario Analysis**: Price predictions based on different market scenarios
-- **Get Resistance Support**: Historical resistance and support levels
-
-## OHLCV Data
-- **Get Hourly OHLCV**: Hourly Open, High, Low, Close, Volume data
-- **Get Daily OHLCV**: Daily OHLCV data for historical analysis
-
-## Grading Systems
-- **Get TM Grades**: Latest Token Metrics grades with trader and quant scores
-- **Get TM Grades Historical**: Historical TM Grade data over time
-- **Get Fundamental Grades**: Fundamental analysis scores (community, exchange, VC, tokenomics)
-- **Get Fundamental Grades Historical**: Historical fundamental grade data
-- **Get Technology Grades**: Technology assessment scores (activity, security, repository)
-- **Get Technology Grades Historical**: Historical technology grade data
-
-## Advanced Analytics
-- **Get AI Reports**: Comprehensive AI-generated token analysis reports
-- **Get Quantmetrics**: Advanced quantitative metrics and analysis
-- **Get Crypto Investors**: Latest crypto investor data and scores
-
-## Indices & Performance
-- **Get Indices**: Access active and passive crypto indices
-- **Get Indices Holdings**: Current holdings and weightings for specific indices
-- **Get Indices Performance**: Historical performance data for crypto indices
+# Available Components
+
+This component provides pre-built actions for all major Token Metrics API endpoints, covering token data, AI-powered analytics, market metrics, trading signals, grading systems, and more. All actions support filtering, pagination, and use API key authentication.
 
 # Example Use Cases
 
-## Automated Trading Systems
-```javascript
-// Monitor trading signals and execute automated trades
-const signals = await steps.token_metrics.getTradingSignals({
-  symbol: "BTC,ETH",
-  signal: "1" // Bullish signals only
-});
-
-// Process signals and trigger trading actions
-```
-
-## Portfolio Management Dashboard
-```javascript
-// Create comprehensive portfolio tracking
-const tokens = await steps.token_metrics.getTokens({
-  category: "defi,layer-1",
-  limit: 100
-});
-
-const grades = await steps.token_metrics.getTmGrades({
-  token_id: tokens.data.map(t => t.token_id).join(",")
-});
-
-// Combine data for portfolio analysis
-```
-
-## Market Research Automation
-```javascript
-// Generate detailed investment research
-const aiReports = await steps.token_metrics.getAiReports({
-  symbol: "SOL,AVAX"
-});
-
-const fundamentals = await steps.token_metrics.getFundamentalGrades({
-  symbol: "SOL,AVAX"
-});
-
-// Create comprehensive research reports
-```
-
-## Risk Management System
-```javascript
-// Monitor market conditions and correlations
-const marketMetrics = await steps.token_metrics.getMarketMetrics({
-  start_date: "2025-07-01",
-  end_date: "2025-07-10"
-});
-
-const correlations = await steps.token_metrics.getCorrelation({
-  symbol: "BTC"
-});
-
-// Implement risk management strategies
-```
+- **Automated Trading Systems**: Monitor AI-generated trading signals and execute automated trades
+- **Portfolio Management**: Track cryptocurrency portfolios with comprehensive token metrics and grades  
+- **Market Research**: Generate detailed investment analysis using AI reports and fundamental data
+- **Risk Management**: Monitor market conditions, correlations, and implement risk strategies
+- **Price Monitoring**: Track token prices and receive alerts on significant market movements
 
 # API Endpoint
 
@@ -139,12 +54,7 @@ Please refer to the [Token Metrics API documentation](https://developers.tokenme
 
 # Data Filtering & Pagination
 
-Most actions support comprehensive filtering options:
-
-- **Token Identification**: Filter by `token_id`, `symbol`, or `token_name`
-- **Market Filters**: Filter by `category`, `exchange`, `market_cap`, `volume`, `fdv`
-- **Date Ranges**: Use `start_date` and `end_date` for historical data
-- **Pagination**: Control results with `limit` (default: 50) and `page` (default: 1) parameters
+Actions support comprehensive filtering by token identifiers, market criteria, date ranges, and standard pagination controls. See the [Token Metrics API documentation](https://developers.tokenmetrics.com/) for specific filter options.
 
 # Error Handling
 
@@ -170,9 +80,3 @@ The component includes comprehensive error handling for common scenarios:
 - **Pipedream Community**: For integration and workflow assistance
 - **Component Issues**: Report bugs or request features via the Pipedream platform
 - **Email Support**: [email protected] for API-related issues
-
-# Version
-
-Current version: 0.0.1
-
-Built with Pipedream Platform v3.0.3

components/token_metrics/actions/get-ai-reports/get-ai-reports.mjs

@@ -1,5 +1,5 @@
 import tokenMetrics from "../../token_metrics.app.mjs";
-import { ENDPOINTS, FILTER_DEFINITIONS } from "../../common/constants.mjs";
+import { ENDPOINTS } from "../../common/constants.mjs";
 import { buildParams, generateFilterSummary } from "../../common/utils.mjs";
 
 const endpoint = ENDPOINTS.AI_REPORTS;
@@ -12,14 +12,20 @@ export default {
   type: "action",
   props: {
     tokenMetrics,
-    // Filter props based on endpoint configuration and API documentation
+    // Filter props using propDefinitions from the app
     tokenId: {
-      ...FILTER_DEFINITIONS.token_id,
-      description: "Comma Separated Token IDs. Click here to access the list of token IDs. Example: 37493,3484",
+      propDefinition: [
+        tokenMetrics,
+        "tokenId",
+      ],
+      description: "Select Token IDs to get AI reports for. Example: `37493,3484`",
     },
     symbol: {
-      ...FILTER_DEFINITIONS.symbol,
-      description: "Comma Separated Token Symbols. Click here to access the list of token symbols. Example: APX,PAAL",
+      propDefinition: [
+        tokenMetrics,
+        "symbol",
+      ],
+      description: "Select token symbols to get AI reports for. Example: `APX,PAAL`",
     },
     // Pagination props
     limit: {
@@ -35,41 +41,26 @@ export default {
         tokenMetrics,
         "page",
       ],
-      description: "Enables pagination and data retrieval control by skipping a specified number of items before fetching data. Page should be a non-negative integer, with 1 indicating the beginning of the dataset. Defaults to 1",
+      min: 1,
       default: 1,
     },
   },
   async run({ $ }) {
     // Build parameters using utility function
     const params = buildParams(this, endpoint.filters);
 
-    try {
-      const response = await this.tokenMetrics.getAiReports({
-        $,
-        params,
-      });
+    const response = await this.tokenMetrics.getAiReports({
+      $,
+      params,
+    });
 
-      // Generate summary using utility function
-      const filterSummary = generateFilterSummary(this, endpoint.filters);
-      
-      // Use $ context for export
-      if ($ && $.export) {
-        const dataLength = response.data?.length || 0;
-        $.export("$summary", `Successfully retrieved AI reports for ${dataLength} tokens${filterSummary}`);
-      }
-      
-      return response;
-    } catch (error) {
-      // Enhanced error handling
-      const errorMessage = error.response?.data?.message || error.message || "An error occurred";
-      const statusCode = error.response?.status;
-      
-      if ($ && $.export) {
-        $.export("$summary", `Error: ${errorMessage}`);
-      }
-      
-      // Throw a more descriptive error
-      throw new Error(`Token Metrics API Error (${statusCode || 'Unknown'}): ${errorMessage}`);
-    }
+    // Generate summary using utility function
+    const filterSummary = generateFilterSummary(this, endpoint.filters);
+    
+    // Use $ context for export
+    const dataLength = response.data?.length || 0;
+    $.export("$summary", `Successfully retrieved AI reports for ${dataLength} tokens${filterSummary}`);
+    
+    return response;
   },
 };

components/token_metrics/actions/get-correlation/get-correlation.mjs

@@ -1,5 +1,5 @@
 import tokenMetrics from "../../token_metrics.app.mjs";
-import { ENDPOINTS, FILTER_DEFINITIONS } from "../../common/constants.mjs";
+import { ENDPOINTS } from "../../common/constants.mjs";
 import { buildParams, generateFilterSummary } from "../../common/utils.mjs";
 
 const endpoint = ENDPOINTS.CORRELATION;
@@ -14,20 +14,30 @@ export default {
     tokenMetrics,
     // Filter props based on endpoint configuration and API documentation
     tokenId: {
-      ...FILTER_DEFINITIONS.token_id,
-      description: "Comma Separated Token IDs. Click here to access the list of token IDs. Example: 3375,3306",
+      propDefinition: [
+        tokenMetrics,
+        "tokenId",
+      ],
     },
     symbol: {
-      ...FILTER_DEFINITIONS.symbol,
-      description: "Comma Separated Token Symbols. Click here to access the list of token symbols. Example: BTC,ETH",
+      propDefinition: [
+        tokenMetrics,
+        "symbol",
+      ],
     },
     category: {
-      ...FILTER_DEFINITIONS.category,
-      description: "Comma separated category name. Click here to access the list of categories. Example: layer-1,nft",
+      propDefinition: [
+        tokenMetrics,
+        "category",
+      ],
+      description: "Select categories to filter results. Example: `layer-1,nft`",
     },
     exchange: {
-      ...FILTER_DEFINITIONS.exchange,
-      description: "Comma separated exchange name. Click here to access the list of exchanges. Example: gate,binance",
+      propDefinition: [
+        tokenMetrics,
+        "exchange",
+      ],
+      description: "Select exchanges to filter results. Example: `gate,binance`",
     },
     // Pagination props
     limit: {
@@ -43,41 +53,26 @@ export default {
         tokenMetrics,
         "page",
       ],
-      description: "Enables pagination and data retrieval control by skipping a specified number of items before fetching data. Page should be a non-negative integer, with 1 indicating the beginning of the dataset. Defaults to 1",
+      min: 1,
       default: 1,
     },
   },
   async run({ $ }) {
     // Build parameters using utility function
     const params = buildParams(this, endpoint.filters);
 
-    try {
-      const response = await this.tokenMetrics.getCorrelation({
-        $,
-        params,
-      });
+    const response = await this.tokenMetrics.getCorrelation({
+      $,
+      params,
+    });
 
-      // Generate summary using utility function
-      const filterSummary = generateFilterSummary(this, endpoint.filters);
-      
-      // Use $ context for export
-      if ($ && $.export) {
-        const dataLength = response.data?.length || 0;
-        $.export("$summary", `Successfully retrieved correlation data for ${dataLength} tokens${filterSummary}`);
-      }
-      
-      return response;
-    } catch (error) {
-      // Enhanced error handling
-      const errorMessage = error.response?.data?.message || error.message || "An error occurred";
-      const statusCode = error.response?.status;
-      
-      if ($ && $.export) {
-        $.export("$summary", `Error: ${errorMessage}`);
-      }
-      
-      // Throw a more descriptive error
-      throw new Error(`Token Metrics API Error (${statusCode || 'Unknown'}): ${errorMessage}`);
-    }
+    // Generate summary using utility function
+    const filterSummary = generateFilterSummary(this, endpoint.filters);
+    
+    // Use $ context for export
+    const dataLength = response.data?.length || 0;
+    $.export("$summary", `Successfully retrieved correlation data for ${dataLength} tokens${filterSummary}`);
+    
+    return response;
   },
 };

components/token_metrics/actions/get-crypto-investors/get-crypto-investors.mjs

@@ -1,5 +1,5 @@
 import tokenMetrics from "../../token_metrics.app.mjs";
-import { ENDPOINTS, FILTER_DEFINITIONS } from "../../common/constants.mjs";
+import { ENDPOINTS } from "../../common/constants.mjs";
 import { buildParams, generateFilterSummary } from "../../common/utils.mjs";
 
 const endpoint = ENDPOINTS.CRYPTO_INVESTORS;
@@ -26,41 +26,26 @@ export default {
         tokenMetrics,
         "page",
       ],
-      description: "Enables pagination and data retrieval control by skipping a specified number of items before fetching data. Page should be a non-negative integer, with 1 indicating the beginning of the dataset. Defaults to 1",
+      min: 1,
       default: 1,
     },
   },
   async run({ $ }) {
     // Build parameters using utility function
     const params = buildParams(this, endpoint.filters);
 
-    try {
-      const response = await this.tokenMetrics.getCryptoInvestors({
-        $,
-        params,
-      });
+    const response = await this.tokenMetrics.getCryptoInvestors({
+      $,
+      params,
+    });
 
-      // Generate summary using utility function
-      const filterSummary = generateFilterSummary(this, endpoint.filters);
-      
-      // Use $ context for export
-      if ($ && $.export) {
-        const dataLength = response.data?.length || 0;
-        $.export("$summary", `Successfully retrieved ${dataLength} crypto investors${filterSummary}`);
-      }
-      
-      return response;
-    } catch (error) {
-      // Enhanced error handling
-      const errorMessage = error.response?.data?.message || error.message || "An error occurred";
-      const statusCode = error.response?.status;
-      
-      if ($ && $.export) {
-        $.export("$summary", `Error: ${errorMessage}`);
-      }
-      
-      // Throw a more descriptive error
-      throw new Error(`Token Metrics API Error (${statusCode || 'Unknown'}): ${errorMessage}`);
-    }
+    // Generate summary using utility function
+    const filterSummary = generateFilterSummary(this, endpoint.filters);
+    
+    // Use $ context for export
+    const dataLength = response.data?.length || 0;
+    $.export("$summary", `Successfully retrieved ${dataLength} crypto investors${filterSummary}`);
+    
+    return response;
   },
 };