@juspay/neurolink 7.7.1 → 7.9.0

package/dist/providers/sagemaker/diagnostics.js

@@ -0,0 +1,137 @@
+/**
+ * SageMaker Simple Diagnostics Module
+ *
+ * Provides basic diagnostic functions for SageMaker configuration and connectivity.
+ */
+import chalk from "chalk";
+import { checkSageMakerConfiguration } from "./config.js";
+import { createSageMakerProvider } from "./index.js";
+/**
+ * Run quick diagnostics for SageMaker configuration
+ */
+export async function runQuickDiagnostics(endpoint) {
+    const results = [];
+    // Test 1: Configuration check
+    try {
+        const configStatus = checkSageMakerConfiguration();
+        results.push({
+            name: "Configuration Validation",
+            category: "configuration",
+            status: configStatus.configured ? "pass" : "fail",
+            message: configStatus.configured
+                ? "SageMaker configuration is valid"
+                : "SageMaker configuration has issues",
+            details: configStatus.issues.join(", "),
+            recommendation: configStatus.configured
+                ? undefined
+                : "Run 'neurolink sagemaker setup' to configure",
+        });
+    }
+    catch (error) {
+        results.push({
+            name: "Configuration Validation",
+            category: "configuration",
+            status: "fail",
+            message: "Failed to validate configuration",
+            details: error instanceof Error ? error.message : String(error),
+            recommendation: "Check your AWS credentials and configuration",
+        });
+    }
+    // Test 2: Connectivity check (if endpoint provided)
+    if (endpoint) {
+        try {
+            const provider = createSageMakerProvider(undefined, endpoint);
+            const connectivityTest = await provider.testConnectivity();
+            results.push({
+                name: `Endpoint Connectivity (${endpoint})`,
+                category: "connectivity",
+                status: connectivityTest.success ? "pass" : "fail",
+                message: connectivityTest.success
+                    ? "Endpoint is accessible"
+                    : "Endpoint connectivity failed",
+                details: connectivityTest.error || "Connection successful",
+                recommendation: connectivityTest.success
+                    ? undefined
+                    : "Check endpoint name and AWS permissions",
+            });
+        }
+        catch (error) {
+            results.push({
+                name: `Endpoint Connectivity (${endpoint})`,
+                category: "connectivity",
+                status: "fail",
+                message: "Connectivity test failed",
+                details: error instanceof Error ? error.message : String(error),
+                recommendation: "Verify endpoint exists and you have access",
+            });
+        }
+    }
+    // Calculate summary
+    const passed = results.filter((r) => r.status === "pass").length;
+    const failed = results.filter((r) => r.status === "fail").length;
+    const warnings = results.filter((r) => r.status === "warning").length;
+    let overallStatus = "healthy";
+    if (failed > 0) {
+        overallStatus = failed >= results.length / 2 ? "critical" : "issues";
+    }
+    else if (warnings > 0) {
+        overallStatus = "issues";
+    }
+    return {
+        overallStatus,
+        results,
+        summary: {
+            total: results.length,
+            passed,
+            failed,
+            warnings,
+        },
+    };
+}
+/**
+ * Format diagnostic report for console output
+ */
+export function formatDiagnosticReport(report) {
+    const lines = [];
+    lines.push(chalk.blue("🔍 SageMaker Diagnostic Results\n"));
+    // Summary
+    lines.push(`📊 Summary: ${report.summary.passed}/${report.summary.total} tests passed`);
+    if (report.summary.failed > 0) {
+        lines.push(chalk.red(`   Failed: ${report.summary.failed}`));
+    }
+    if (report.summary.warnings > 0) {
+        lines.push(chalk.yellow(`   Warnings: ${report.summary.warnings}`));
+    }
+    lines.push("");
+    // Individual results
+    report.results.forEach((result, index) => {
+        const icon = result.status === "pass" ? "✅" : result.status === "fail" ? "❌" : "⚠️";
+        const color = result.status === "pass"
+            ? chalk.green
+            : result.status === "fail"
+                ? chalk.red
+                : chalk.yellow;
+        lines.push(`${index + 1}. ${icon} ${color(result.name)}`);
+        lines.push(`   ${result.message}`);
+        if (result.details) {
+            lines.push(`   Details: ${result.details}`);
+        }
+        if (result.recommendation) {
+            lines.push(chalk.blue(`   💡 ${result.recommendation}`));
+        }
+        lines.push("");
+    });
+    // Overall status
+    const statusIcon = report.overallStatus === "healthy"
+        ? "✅"
+        : report.overallStatus === "issues"
+            ? "⚠️"
+            : "🚨";
+    const statusColor = report.overallStatus === "healthy"
+        ? chalk.green
+        : report.overallStatus === "issues"
+            ? chalk.yellow
+            : chalk.red;
+    lines.push(`${statusIcon} Overall Status: ${statusColor(report.overallStatus.toUpperCase())}`);
+    return lines.join("\n");
+}

package/dist/providers/sagemaker/error-constants.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Error message constants and templates for Amazon SageMaker Provider
+ *
+ * This module contains all error message templates, prefixes, and constants
+ * used throughout the SageMaker provider for consistent error handling.
+ */
+/**
+ * Error message prefixes for different error types
+ */
+export declare const ERROR_MESSAGE_PREFIXES: {
+    readonly VALIDATION: "Invalid request parameters";
+    readonly MODEL: "Model execution error";
+    readonly INTERNAL: "Internal server error";
+    readonly SERVICE_UNAVAILABLE: "SageMaker service is temporarily unavailable";
+    readonly THROTTLING: "Request rate limit exceeded";
+    readonly CREDENTIALS: "AWS credentials are invalid or missing";
+    readonly NETWORK: "Network error while connecting to SageMaker";
+    readonly ENDPOINT_NOT_FOUND: "SageMaker endpoint not found";
+    readonly VALIDATION_FIELD: "Validation failed for";
+    readonly CREDENTIALS_SETUP: "AWS credentials error";
+    readonly NETWORK_CONNECTION: "Network error";
+};
+/**
+ * Detailed error message templates for user guidance
+ */
+export declare const ERROR_MESSAGE_TEMPLATES: {
+    readonly VALIDATION_ERROR: "❌ SageMaker Request Validation Error{endpointContext}\n\n{originalMessage}\n\n🔧 Common Solutions:\n1. Check your request parameters and format\n2. Verify the endpoint name is correct\n3. Ensure your request body matches the expected model format\n4. Validate that required parameters are included\n\n💡 Tips:\n- Double-check the endpoint name spelling\n- Ensure JSON format is valid if using JSON content type\n- Verify parameter types match model expectations";
+    readonly MODEL_ERROR: "❌ SageMaker Model Execution Error{endpointContext}\n\n{originalMessage}\n\n🔧 Common Solutions:\n1. Check if the model is properly deployed and in 'InService' status\n2. Verify your input format matches what the model expects\n3. Ensure input size is within model limits\n4. Check if the model container is healthy\n\n💡 Tips:\n- Try with a simpler input to test model health\n- Check CloudWatch logs for detailed model errors\n- Verify model dependencies are properly installed";
+    readonly INTERNAL_ERROR: "❌ SageMaker Internal Server Error{endpointContext}\n\n{originalMessage}\n\n🔧 Common Solutions:\n1. Retry the request after a short delay\n2. Check AWS Service Health Dashboard\n3. Verify your endpoint is still active and healthy\n4. Contact AWS support if issue persists\n\n💡 Tips:\n- This is usually a temporary issue\n- Implement exponential backoff for retries\n- Check if other endpoints are working";
+    readonly SERVICE_UNAVAILABLE: "❌ SageMaker Service Temporarily Unavailable{endpointContext}\n\n{originalMessage}\n\n🔧 Common Solutions:\n1. Wait and retry after a few seconds\n2. Check AWS region status\n3. Verify your endpoint hasn't been deleted\n4. Check if you've hit account limits\n\n💡 Tips:\n- Service issues are usually temporary\n- Implement retry logic with backoff\n- Monitor AWS Service Health Dashboard";
+    readonly CREDENTIALS_ERROR: "❌ AWS Credentials Error{endpointContext}\n\n{originalMessage}\n\n🔧 Required Steps:\n1. Verify AWS_ACCESS_KEY_ID is set correctly\n2. Verify AWS_SECRET_ACCESS_KEY is set correctly\n3. Check AWS_SESSION_TOKEN if using temporary credentials\n4. Ensure credentials have SageMaker permissions\n\n🔑 Required IAM Permissions:\n- sagemaker:InvokeEndpoint\n- sagemaker:InvokeEndpointWithResponseStream\n- sagemaker:DescribeEndpoint (optional, for debugging)\n\n💡 Setup Help:\n- Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables\n- Check IAM user has necessary permissions\n- Verify credentials haven't expired";
+    readonly NETWORK_ERROR: "❌ Network Connection Error{endpointContext}\n\n{originalMessage}\n\n🔧 Common Solutions:\n1. Check your internet connection\n2. Verify firewall/proxy settings\n3. Try different DNS servers\n4. Check if SageMaker service is accessible from your network\n\n💡 Network Troubleshooting:\n- Test connectivity to other AWS services\n- Check for VPC/subnet restrictions if running in AWS\n- Verify security group rules allow outbound HTTPS";
+    readonly ENDPOINT_NOT_FOUND: "❌ SageMaker Endpoint Not Found{endpointContext}\n\n{originalMessage}\n\n🔧 Common Solutions:\n1. Verify the endpoint name is spelled correctly\n2. Check if the endpoint exists in the correct AWS region\n3. Ensure the endpoint is in 'InService' status\n4. Verify you have permissions to access the endpoint\n\n💡 Endpoint Management:\n- List endpoints: aws sagemaker list-endpoints\n- Check status: aws sagemaker describe-endpoint --endpoint-name <name>\n- Ensure endpoint is deployed in the same region";
+    readonly THROTTLING_ERROR: "❌ Request Rate Limit Exceeded{endpointContext}\n\n{originalMessage}\n\n🔧 Common Solutions:\n1. Implement exponential backoff retry logic\n2. Reduce request rate\n3. Consider using batch inference for large workloads\n4. Request higher limits from AWS support if needed\n\n💡 Rate Limiting Tips:\n- Space out requests over time\n- Use batch processing when possible\n- Monitor your request patterns\n- Consider auto-scaling your endpoint";
+    readonly UNKNOWN_ERROR: "❌ Unknown SageMaker Error{endpointContext}\n\n{originalMessage}\n\n🔧 General Troubleshooting:\n1. Check AWS credentials and permissions\n2. Verify endpoint name and status\n3. Check network connectivity\n4. Review request format and parameters\n\n💡 Additional Help:\n- Check CloudWatch logs for detailed errors\n- Verify SageMaker service health\n- Consult AWS SageMaker documentation\n- Contact AWS support for persistent issues";
+    readonly DEFAULT: "❌ SageMaker Error{endpointContext}\n\n{originalMessage}\n\n🔧 General Troubleshooting:\n1. Check AWS credentials and permissions\n2. Verify endpoint name and status\n3. Check network connectivity\n4. Review request format and parameters\n\n💡 Additional Help:\n- Check CloudWatch logs for detailed errors\n- Verify SageMaker service health\n- Consult AWS SageMaker documentation\n- Contact AWS support for persistent issues";
+};
+/**
+ * Retry delay constants for different error types (in milliseconds)
+ */
+export declare const RETRY_DELAYS: {
+    readonly THROTTLING_ERROR: 5000;
+    readonly SERVICE_UNAVAILABLE: 2000;
+    readonly NETWORK_ERROR: 1000;
+    readonly DEFAULT: 1000;
+};
+/**
+ * List of retryable AWS SDK error names and conditions
+ */
+export declare const RETRYABLE_ERROR_CONDITIONS: {
+    readonly ERROR_NAMES: readonly ["ServiceUnavailable", "InternalFailure", "ThrottlingException", "NetworkingError"];
+    readonly ERROR_MESSAGE_KEYWORDS: readonly ["timeout", "throttl", "unavailable", "internal", "network"];
+};
+/**
+ * AWS SDK error name mappings to SageMaker error codes
+ */
+export declare const AWS_ERROR_MAPPINGS: {
+    readonly ValidationException: "VALIDATION_ERROR";
+    readonly ModelError: "MODEL_ERROR";
+    readonly InternalFailure: "INTERNAL_ERROR";
+    readonly ServiceUnavailable: "SERVICE_UNAVAILABLE";
+    readonly ThrottlingException: "THROTTLING_ERROR";
+    readonly CredentialsError: "CREDENTIALS_ERROR";
+    readonly NetworkingError: "NETWORK_ERROR";
+};
+/**
+ * Common error message keywords for pattern matching
+ */
+export declare const ERROR_KEYWORDS: {
+    readonly VALIDATION: readonly ["validation"];
+    readonly MODEL: readonly ["model error"];
+    readonly INTERNAL: readonly ["internal"];
+    readonly SERVICE_UNAVAILABLE: readonly ["unavailable"];
+    readonly THROTTLING: readonly ["throttl"];
+    readonly CREDENTIALS: readonly ["credential"];
+    readonly NETWORK: readonly ["network"];
+    readonly ENDPOINT_NOT_FOUND: readonly ["endpoint", "not found"];
+};

package/dist/providers/sagemaker/error-constants.js

@@ -0,0 +1,227 @@
+/**
+ * Error message constants and templates for Amazon SageMaker Provider
+ *
+ * This module contains all error message templates, prefixes, and constants
+ * used throughout the SageMaker provider for consistent error handling.
+ */
+/**
+ * Error message prefixes for different error types
+ */
+export const ERROR_MESSAGE_PREFIXES = {
+    VALIDATION: "Invalid request parameters",
+    MODEL: "Model execution error",
+    INTERNAL: "Internal server error",
+    SERVICE_UNAVAILABLE: "SageMaker service is temporarily unavailable",
+    THROTTLING: "Request rate limit exceeded",
+    CREDENTIALS: "AWS credentials are invalid or missing",
+    NETWORK: "Network error while connecting to SageMaker",
+    ENDPOINT_NOT_FOUND: "SageMaker endpoint not found",
+    VALIDATION_FIELD: "Validation failed for",
+    CREDENTIALS_SETUP: "AWS credentials error",
+    NETWORK_CONNECTION: "Network error",
+};
+/**
+ * Detailed error message templates for user guidance
+ */
+export const ERROR_MESSAGE_TEMPLATES = {
+    VALIDATION_ERROR: `❌ SageMaker Request Validation Error{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Check your request parameters and format
+2. Verify the endpoint name is correct
+3. Ensure your request body matches the expected model format
+4. Validate that required parameters are included
+
+💡 Tips:
+- Double-check the endpoint name spelling
+- Ensure JSON format is valid if using JSON content type
+- Verify parameter types match model expectations`,
+    MODEL_ERROR: `❌ SageMaker Model Execution Error{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Check if the model is properly deployed and in 'InService' status
+2. Verify your input format matches what the model expects
+3. Ensure input size is within model limits
+4. Check if the model container is healthy
+
+💡 Tips:
+- Try with a simpler input to test model health
+- Check CloudWatch logs for detailed model errors
+- Verify model dependencies are properly installed`,
+    INTERNAL_ERROR: `❌ SageMaker Internal Server Error{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Retry the request after a short delay
+2. Check AWS Service Health Dashboard
+3. Verify your endpoint is still active and healthy
+4. Contact AWS support if issue persists
+
+💡 Tips:
+- This is usually a temporary issue
+- Implement exponential backoff for retries
+- Check if other endpoints are working`,
+    SERVICE_UNAVAILABLE: `❌ SageMaker Service Temporarily Unavailable{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Wait and retry after a few seconds
+2. Check AWS region status
+3. Verify your endpoint hasn't been deleted
+4. Check if you've hit account limits
+
+💡 Tips:
+- Service issues are usually temporary
+- Implement retry logic with backoff
+- Monitor AWS Service Health Dashboard`,
+    CREDENTIALS_ERROR: `❌ AWS Credentials Error{endpointContext}
+
+{originalMessage}
+
+🔧 Required Steps:
+1. Verify AWS_ACCESS_KEY_ID is set correctly
+2. Verify AWS_SECRET_ACCESS_KEY is set correctly
+3. Check AWS_SESSION_TOKEN if using temporary credentials
+4. Ensure credentials have SageMaker permissions
+
+🔑 Required IAM Permissions:
+- sagemaker:InvokeEndpoint
+- sagemaker:InvokeEndpointWithResponseStream
+- sagemaker:DescribeEndpoint (optional, for debugging)
+
+💡 Setup Help:
+- Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables
+- Check IAM user has necessary permissions
+- Verify credentials haven't expired`,
+    NETWORK_ERROR: `❌ Network Connection Error{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Check your internet connection
+2. Verify firewall/proxy settings
+3. Try different DNS servers
+4. Check if SageMaker service is accessible from your network
+
+💡 Network Troubleshooting:
+- Test connectivity to other AWS services
+- Check for VPC/subnet restrictions if running in AWS
+- Verify security group rules allow outbound HTTPS`,
+    ENDPOINT_NOT_FOUND: `❌ SageMaker Endpoint Not Found{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Verify the endpoint name is spelled correctly
+2. Check if the endpoint exists in the correct AWS region
+3. Ensure the endpoint is in 'InService' status
+4. Verify you have permissions to access the endpoint
+
+💡 Endpoint Management:
+- List endpoints: aws sagemaker list-endpoints
+- Check status: aws sagemaker describe-endpoint --endpoint-name <name>
+- Ensure endpoint is deployed in the same region`,
+    THROTTLING_ERROR: `❌ Request Rate Limit Exceeded{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Implement exponential backoff retry logic
+2. Reduce request rate
+3. Consider using batch inference for large workloads
+4. Request higher limits from AWS support if needed
+
+💡 Rate Limiting Tips:
+- Space out requests over time
+- Use batch processing when possible
+- Monitor your request patterns
+- Consider auto-scaling your endpoint`,
+    UNKNOWN_ERROR: `❌ Unknown SageMaker Error{endpointContext}
+
+{originalMessage}
+
+🔧 General Troubleshooting:
+1. Check AWS credentials and permissions
+2. Verify endpoint name and status
+3. Check network connectivity
+4. Review request format and parameters
+
+💡 Additional Help:
+- Check CloudWatch logs for detailed errors
+- Verify SageMaker service health
+- Consult AWS SageMaker documentation
+- Contact AWS support for persistent issues`,
+    DEFAULT: `❌ SageMaker Error{endpointContext}
+
+{originalMessage}
+
+🔧 General Troubleshooting:
+1. Check AWS credentials and permissions
+2. Verify endpoint name and status
+3. Check network connectivity
+4. Review request format and parameters
+
+💡 Additional Help:
+- Check CloudWatch logs for detailed errors
+- Verify SageMaker service health
+- Consult AWS SageMaker documentation
+- Contact AWS support for persistent issues`,
+};
+/**
+ * Retry delay constants for different error types (in milliseconds)
+ */
+export const RETRY_DELAYS = {
+    THROTTLING_ERROR: 5000, // 5 seconds for throttling
+    SERVICE_UNAVAILABLE: 2000, // 2 seconds for service issues
+    NETWORK_ERROR: 1000, // 1 second for network issues
+    DEFAULT: 1000, // Default 1 second
+};
+/**
+ * List of retryable AWS SDK error names and conditions
+ */
+export const RETRYABLE_ERROR_CONDITIONS = {
+    ERROR_NAMES: [
+        "ServiceUnavailable",
+        "InternalFailure",
+        "ThrottlingException",
+        "NetworkingError",
+    ],
+    ERROR_MESSAGE_KEYWORDS: [
+        "timeout",
+        "throttl",
+        "unavailable",
+        "internal",
+        "network",
+    ],
+};
+/**
+ * AWS SDK error name mappings to SageMaker error codes
+ */
+export const AWS_ERROR_MAPPINGS = {
+    ValidationException: "VALIDATION_ERROR",
+    ModelError: "MODEL_ERROR",
+    InternalFailure: "INTERNAL_ERROR",
+    ServiceUnavailable: "SERVICE_UNAVAILABLE",
+    ThrottlingException: "THROTTLING_ERROR",
+    CredentialsError: "CREDENTIALS_ERROR",
+    NetworkingError: "NETWORK_ERROR",
+};
+/**
+ * Common error message keywords for pattern matching
+ */
+export const ERROR_KEYWORDS = {
+    VALIDATION: ["validation"],
+    MODEL: ["model error"],
+    INTERNAL: ["internal"],
+    SERVICE_UNAVAILABLE: ["unavailable"],
+    THROTTLING: ["throttl"],
+    CREDENTIALS: ["credential"],
+    NETWORK: ["network"],
+    ENDPOINT_NOT_FOUND: ["endpoint", "not found"],
+};

package/dist/providers/sagemaker/errors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Error handling system for Amazon SageMaker Provider
+ *
+ * This module provides comprehensive error handling, categorization,
+ * and user-friendly error messages for SageMaker operations.
+ */
+import type { SageMakerErrorCode, SageMakerErrorInfo } from "./types.js";
+/**
+ * Custom error class for SageMaker-specific errors
+ */
+export declare class SageMakerError extends Error {
+    readonly code: SageMakerErrorCode;
+    readonly statusCode?: number;
+    readonly cause?: Error;
+    readonly endpoint?: string;
+    readonly requestId?: string;
+    readonly retryable: boolean;
+    constructor(message: string, code?: SageMakerErrorCode, statusCode?: number, cause?: Error, endpoint?: string, requestId?: string, retryable?: boolean);
+    /**
+     * Convert error to JSON for logging/serialization
+     */
+    toJSON(): SageMakerErrorInfo & {
+        stack?: string;
+    };
+    /**
+     * Get user-friendly error message with troubleshooting guidance
+     */
+    getUserFriendlyMessage(): string;
+    /**
+     * Check if this error type is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Get recommended retry delay in milliseconds
+     */
+    getRetryDelay(): number;
+}
+/**
+ * Main error handler for SageMaker operations
+ *
+ * @param error - Original error from AWS SDK or other operations
+ * @param endpoint - Endpoint name where error occurred (optional)
+ * @returns Categorized SageMakerError with user guidance
+ */
+export declare function handleSageMakerError(error: unknown, endpoint?: string): SageMakerError;
+/**
+ * Create a validation error for configuration issues
+ *
+ * @param message - Validation error message
+ * @param field - Configuration field that failed validation
+ * @returns SageMakerError with validation details
+ */
+export declare function createValidationError(message: string, field?: string): SageMakerError;
+/**
+ * Create a credentials error with setup guidance
+ *
+ * @param message - Credentials error message
+ * @returns SageMakerError with credentials guidance
+ */
+export declare function createCredentialsError(message: string): SageMakerError;
+/**
+ * Create a network error with connectivity guidance
+ *
+ * @param message - Network error message
+ * @param endpoint - Endpoint that failed to connect
+ * @returns SageMakerError with network guidance
+ */
+export declare function createNetworkError(message: string, endpoint?: string): SageMakerError;
+/**
+ * Check if an error is retryable based on its characteristics
+ *
+ * @param error - Error to check
+ * @returns True if the error suggests a retry might succeed
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Get recommended retry delay for an error
+ *
+ * @param error - Error to get retry delay for
+ * @param attempt - Current retry attempt number (for exponential backoff)
+ * @returns Recommended delay in milliseconds
+ */
+export declare function getRetryDelay(error: unknown, attempt?: number): number;