ebay-mcp 1.4.3

package/build/utils/communication/notification.js

@@ -0,0 +1,369 @@
+import { z } from 'zod';
+/**
+ * Zod schemas for Notification API input validation
+ * Based on: src/api/communication/notification.ts
+ * OpenAPI spec: docs/sell-apps/communication/commerce_notification_v1_oas3.json
+ * Types from: src/types/commerce_notification_v1_oas3.ts
+ */
+// Reusable schema for limit parameter (string in API)
+const limitSchema = z
+    .string({
+    invalid_type_error: 'limit must be a string',
+    description: 'Maximum number of items to return per page (10-100)',
+})
+    .optional();
+// Reusable schema for continuation token parameter
+const continuationTokenSchema = z
+    .string({
+    message: 'Continuation token must be a string',
+    invalid_type_error: 'continuation_token must be a string',
+    description: 'Token for pagination',
+})
+    .optional();
+// Reusable schema for ID parameters (required)
+const idSchema = (name, description) => z.string({
+    message: `${name} is required`,
+    required_error: `${name.toLowerCase().replace(/\s+/g, '_')} is required`,
+    invalid_type_error: `${name.toLowerCase().replace(/\s+/g, '_')} must be a string`,
+    description,
+});
+// Reusable schema for object data parameters
+const _objectDataSchema = (name, description) => z.record(z.unknown(), {
+    message: `${name} is required`,
+    required_error: `${name.toLowerCase().replace(/\s+/g, '_')} is required`,
+    invalid_type_error: `${name.toLowerCase().replace(/\s+/g, '_')} must be an object`,
+    description,
+});
+/**
+ * Schema for getPublicKey method
+ * Endpoint: GET /public_key/{public_key_id}
+ * Path: GetPublicKeyParams - public_key_id (required)
+ */
+export const getPublicKeySchema = z.object({
+    public_key_id: idSchema('Public key ID', 'The unique identifier for the public key'),
+});
+/**
+ * Schema for getConfig method
+ * Endpoint: GET /config
+ */
+export const getConfigSchema = z.object({});
+/**
+ * Schema for updateConfig method
+ * Endpoint: PUT /config
+ * Body: ConfigType - alertEmail
+ */
+export const updateConfigSchema = z.object({
+    alert_email: z
+        .string({
+        invalid_type_error: 'alert_email must be a string',
+        description: 'Email address for Notification API alerts',
+    })
+        .email({
+        message: 'alert_email must be a valid email address',
+    })
+        .optional(),
+});
+/**
+ * Schema for getDestinations method
+ * Endpoint: GET /destination
+ * Query: DestinationParams - continuation_token, limit
+ */
+export const getDestinationsSchema = z.object({
+    continuation_token: continuationTokenSchema,
+    limit: limitSchema,
+});
+/**
+ * Schema for getDestination method
+ * Endpoint: GET /destination/{destination_id}
+ * Path: destination_id (required)
+ */
+export const getDestinationSchema = z.object({
+    destination_id: idSchema('Destination ID', 'The unique identifier for the destination'),
+});
+/**
+ * Schema for createDestination method
+ * Endpoint: POST /destination
+ * Body: DestinationRequest - deliveryConfig, name, status
+ */
+export const createDestinationSchema = z.object({
+    delivery_config: z
+        .object({
+        endpoint: z
+            .string({
+            invalid_type_error: 'endpoint must be a string',
+            description: 'HTTPS endpoint URL (no internal IPs or localhost)',
+        })
+            .url({
+            message: 'endpoint must be a valid URL',
+        })
+            .optional(),
+        verification_token: z
+            .string({
+            invalid_type_error: 'verification_token must be a string',
+            description: 'Verification token (32-80 alphanumeric, underscore, hyphen characters)',
+        })
+            .min(32, 'verification_token must be at least 32 characters')
+            .max(80, 'verification_token must be at most 80 characters')
+            .regex(/^[a-zA-Z0-9_-]+$/, 'verification_token can only contain alphanumeric, underscore, and hyphen characters')
+            .optional(),
+    }, {
+        invalid_type_error: 'delivery_config must be an object',
+        description: 'Delivery configuration with endpoint and verification token',
+    })
+        .optional(),
+    name: z
+        .string({
+        invalid_type_error: 'name must be a string',
+        description: 'Seller-specified name for the destination',
+    })
+        .optional(),
+    status: z
+        .string({
+        invalid_type_error: 'status must be a string',
+        description: 'Status: ENABLED or DISABLED',
+    })
+        .optional(),
+});
+/**
+ * Schema for updateDestination method
+ * Endpoint: PUT /destination/{destination_id}
+ * Path: destination_id (required)
+ * Body: DestinationRequest
+ */
+export const updateDestinationSchema = z.object({
+    destination_id: idSchema('Destination ID', 'The unique identifier for the destination'),
+    delivery_config: z
+        .object({
+        endpoint: z
+            .string({
+            invalid_type_error: 'endpoint must be a string',
+            description: 'HTTPS endpoint URL',
+        })
+            .url({
+            message: 'endpoint must be a valid URL',
+        })
+            .optional(),
+        verification_token: z
+            .string({
+            invalid_type_error: 'verification_token must be a string',
+            description: 'Verification token (32-80 characters)',
+        })
+            .min(32)
+            .max(80)
+            .regex(/^[a-zA-Z0-9_-]+$/)
+            .optional(),
+    })
+        .optional(),
+    name: z
+        .string({
+        invalid_type_error: 'name must be a string',
+        description: 'Destination name',
+    })
+        .optional(),
+    status: z
+        .string({
+        invalid_type_error: 'status must be a string',
+        description: 'Status: ENABLED or DISABLED',
+    })
+        .optional(),
+});
+/**
+ * Schema for deleteDestination method
+ * Endpoint: DELETE /destination/{destination_id}
+ * Path: destination_id (required)
+ */
+export const deleteDestinationSchema = z.object({
+    destination_id: idSchema('Destination ID', 'The unique identifier for the destination'),
+});
+/**
+ * Schema for getSubscriptions method
+ * Endpoint: GET /subscription
+ * Query: SubscriptionParams - continuation_token, limit
+ */
+export const getSubscriptionsSchema = z.object({
+    limit: limitSchema,
+    continuation_token: continuationTokenSchema,
+});
+/**
+ * Schema for createSubscription method
+ * Endpoint: POST /subscription
+ * Body: CreateSubscriptionRequest - destinationId, payload, status, topicId
+ */
+export const createSubscriptionSchema = z.object({
+    destination_id: z
+        .string({
+        invalid_type_error: 'destination_id must be a string',
+        description: 'The unique identifier of the destination endpoint',
+    })
+        .optional(),
+    payload: z
+        .object({
+        delivery_protocol: z
+            .string({
+            invalid_type_error: 'delivery_protocol must be a string',
+            description: 'Delivery protocol (currently only HTTPS is supported)',
+        })
+            .optional(),
+        format: z
+            .string({
+            invalid_type_error: 'format must be a string',
+            description: 'Payload format (currently only JSON is supported)',
+        })
+            .optional(),
+        schema_version: z
+            .string({
+            invalid_type_error: 'schema_version must be a string',
+            description: 'Schema version for the notification topic',
+        })
+            .optional(),
+    }, {
+        invalid_type_error: 'payload must be an object',
+        description: 'Payload configuration',
+    })
+        .optional(),
+    status: z
+        .string({
+        invalid_type_error: 'status must be a string',
+        description: 'Status: ENABLED or DISABLED',
+    })
+        .optional(),
+    topic_id: z
+        .string({
+        invalid_type_error: 'topic_id must be a string',
+        description: 'The unique identifier of the notification topic',
+    })
+        .optional(),
+});
+/**
+ * Schema for getSubscription method
+ * Endpoint: GET /subscription/{subscription_id}
+ * Path: subscription_id (required)
+ */
+export const getSubscriptionSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+});
+/**
+ * Schema for updateSubscription method
+ * Endpoint: PUT /subscription/{subscription_id}
+ * Path: subscription_id (required)
+ * Body: UpdateSubscriptionRequest - destinationId, payload, status
+ */
+export const updateSubscriptionSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+    destination_id: z
+        .string({
+        invalid_type_error: 'destination_id must be a string',
+        description: 'The unique identifier of the destination',
+    })
+        .optional(),
+    payload: z
+        .object({
+        delivery_protocol: z
+            .string({
+            invalid_type_error: 'delivery_protocol must be a string',
+            description: 'Delivery protocol',
+        })
+            .optional(),
+        format: z
+            .string({
+            invalid_type_error: 'format must be a string',
+            description: 'Payload format',
+        })
+            .optional(),
+        schema_version: z
+            .string({
+            invalid_type_error: 'schema_version must be a string',
+            description: 'Schema version',
+        })
+            .optional(),
+    })
+        .optional(),
+    status: z
+        .string({
+        invalid_type_error: 'status must be a string',
+        description: 'Status: ENABLED or DISABLED',
+    })
+        .optional(),
+});
+/**
+ * Schema for deleteSubscription method
+ * Endpoint: DELETE /subscription/{subscription_id}
+ * Path: subscription_id (required)
+ */
+export const deleteSubscriptionSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+});
+/**
+ * Schema for disableSubscription method
+ * Endpoint: POST /subscription/{subscription_id}/disable
+ * Path: subscription_id (required)
+ */
+export const disableSubscriptionSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+});
+/**
+ * Schema for enableSubscription method
+ * Endpoint: POST /subscription/{subscription_id}/enable
+ * Path: subscription_id (required)
+ */
+export const enableSubscriptionSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+});
+/**
+ * Schema for testSubscription method
+ * Endpoint: POST /subscription/{subscription_id}/test
+ * Path: subscription_id (required)
+ */
+export const testSubscriptionSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+});
+/**
+ * Schema for getTopic method
+ * Endpoint: GET /topic/{topic_id}
+ * Path: topic_id (required)
+ */
+export const getTopicSchema = z.object({
+    topic_id: idSchema('Topic ID', 'The unique identifier for the topic'),
+});
+/**
+ * Schema for getTopics method
+ * Endpoint: GET /topic
+ * Query: TopicParams - continuation_token, limit
+ */
+export const getTopicsSchema = z.object({
+    limit: limitSchema,
+    continuation_token: continuationTokenSchema,
+});
+/**
+ * Schema for createSubscriptionFilter method
+ * Endpoint: POST /subscription/{subscription_id}/filter
+ * Path: subscription_id (required)
+ * Body: CreateSubscriptionFilterRequest - filterSchema
+ */
+export const createSubscriptionFilterSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+    filter_schema: z
+        .record(z.unknown(), {
+        invalid_type_error: 'filter_schema must be an object',
+        description: 'Valid JSON Schema Core document (version 2020-12 or later) to filter notifications',
+    })
+        .optional(),
+});
+/**
+ * Schema for getSubscriptionFilter method
+ * Endpoint: GET /subscription/{subscription_id}/filter/{filter_id}
+ * Path: subscription_id (required), filter_id (required)
+ */
+export const getSubscriptionFilterSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+    filter_id: idSchema('Filter ID', 'The unique identifier for the filter'),
+});
+/**
+ * Schema for deleteSubscriptionFilter method
+ * Endpoint: DELETE /subscription/{subscription_id}/filter/{filter_id}
+ * Path: subscription_id (required), filter_id (required)
+ */
+export const deleteSubscriptionFilterSchema = z.object({
+    subscription_id: idSchema('Subscription ID', 'The unique identifier for the subscription'),
+    filter_id: idSchema('Filter ID', 'The unique identifier for the filter'),
+});

package/build/utils/date-converter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Utility functions for date/timestamp conversion and validation
+ */
+/**
+ * Convert a date string or Date object to Unix timestamp (milliseconds)
+ *
+ * Supported formats:
+ * - ISO 8601: "2025-01-15T10:30:00Z" or "2025-01-15T10:30:00.000Z"
+ * - Date object: new Date()
+ * - Unix timestamp (milliseconds): 1736938200000
+ * - Unix timestamp (seconds): 1736938200
+ * - Relative time: "in 2 hours", "in 7200 seconds"
+ *
+ * @param dateInput - Date string, Date object, or Unix timestamp
+ * @returns Unix timestamp in milliseconds
+ * @throws Error if date format is invalid
+ */
+export declare function convertToTimestamp(dateInput: string | Date | number): number;
+/**
+ * Calculate expiry timestamp from duration in seconds
+ * Useful for eBay token responses which provide expires_in in seconds
+ *
+ * @param expiresInSeconds - Duration in seconds (e.g., 7200 for 2 hours)
+ * @param fromTimestamp - Optional base timestamp (defaults to now)
+ * @returns Expiry timestamp in milliseconds
+ */
+export declare function calculateExpiry(expiresInSeconds: number, fromTimestamp?: number): number;
+/**
+ * Check if a timestamp is expired
+ *
+ * @param expiryTimestamp - Expiry timestamp in milliseconds
+ * @param bufferSeconds - Optional buffer time in seconds (default: 60)
+ * @returns true if expired (or will expire within buffer time)
+ */
+export declare function isExpired(expiryTimestamp: number, bufferSeconds?: number): boolean;
+/**
+ * Get human-readable time remaining until expiry
+ *
+ * @param expiryTimestamp - Expiry timestamp in milliseconds
+ * @returns Human-readable string (e.g., "2 hours 15 minutes")
+ */
+export declare function getTimeRemaining(expiryTimestamp: number): string;
+/**
+ * Validate token expiry times and provide recommendations
+ *
+ * @param accessTokenExpiry - Access token expiry timestamp
+ * @param refreshTokenExpiry - Refresh token expiry timestamp
+ * @returns Validation result with warnings and recommendations
+ */
+export interface TokenExpiryValidation {
+    valid: boolean;
+    accessTokenStatus: 'valid' | 'expiring-soon' | 'expired';
+    refreshTokenStatus: 'valid' | 'expiring-soon' | 'expired';
+    accessTokenRemaining: string;
+    refreshTokenRemaining: string;
+    warnings: string[];
+    recommendations: string[];
+}
+export declare function validateTokenExpiry(accessTokenExpiry: number, refreshTokenExpiry: number): TokenExpiryValidation;

package/build/utils/date-converter.js

@@ -0,0 +1,160 @@
+/**
+ * Utility functions for date/timestamp conversion and validation
+ */
+/**
+ * Convert a date string or Date object to Unix timestamp (milliseconds)
+ *
+ * Supported formats:
+ * - ISO 8601: "2025-01-15T10:30:00Z" or "2025-01-15T10:30:00.000Z"
+ * - Date object: new Date()
+ * - Unix timestamp (milliseconds): 1736938200000
+ * - Unix timestamp (seconds): 1736938200
+ * - Relative time: "in 2 hours", "in 7200 seconds"
+ *
+ * @param dateInput - Date string, Date object, or Unix timestamp
+ * @returns Unix timestamp in milliseconds
+ * @throws Error if date format is invalid
+ */
+export function convertToTimestamp(dateInput) {
+    // If already a number, handle as timestamp
+    if (typeof dateInput === 'number') {
+        // If appears to be seconds (less than year 2100 in milliseconds)
+        if (dateInput < 4102444800000) {
+            // Could be seconds, check if reasonable
+            const now = Date.now();
+            const asSeconds = dateInput * 1000;
+            // If multiplying by 1000 gives reasonable future date, it's seconds
+            if (asSeconds > now - 100 * 365 * 24 * 60 * 60 * 1000) {
+                return Math.floor(asSeconds);
+            }
+        }
+        // Already milliseconds
+        return Math.floor(dateInput);
+    }
+    // If Date object
+    if (dateInput instanceof Date) {
+        const timestamp = dateInput.getTime();
+        if (isNaN(timestamp)) {
+            throw new Error('Invalid Date object');
+        }
+        return timestamp;
+    }
+    // If string, try parsing
+    if (typeof dateInput === 'string') {
+        // Handle relative time: "in X hours/minutes/seconds"
+        const relativeMatch = /^in\s+(\d+)\s+(hours?|minutes?|seconds?|days?)$/i.exec(dateInput);
+        if (relativeMatch) {
+            const amount = parseInt(relativeMatch[1], 10);
+            const unit = relativeMatch[2].toLowerCase();
+            let multiplier = 1000; // Default to seconds
+            if (unit.startsWith('minute'))
+                multiplier = 60 * 1000;
+            else if (unit.startsWith('hour'))
+                multiplier = 60 * 60 * 1000;
+            else if (unit.startsWith('day'))
+                multiplier = 24 * 60 * 60 * 1000;
+            return Date.now() + amount * multiplier;
+        }
+        // Try parsing as ISO date or other standard format
+        const parsed = Date.parse(dateInput);
+        if (isNaN(parsed)) {
+            throw new Error(`Invalid date format: ${dateInput}. Supported formats: ISO 8601, Unix timestamp, or relative time (e.g., "in 2 hours")`);
+        }
+        return parsed;
+    }
+    throw new Error(`Unsupported date input type: ${typeof dateInput}`);
+}
+/**
+ * Calculate expiry timestamp from duration in seconds
+ * Useful for eBay token responses which provide expires_in in seconds
+ *
+ * @param expiresInSeconds - Duration in seconds (e.g., 7200 for 2 hours)
+ * @param fromTimestamp - Optional base timestamp (defaults to now)
+ * @returns Expiry timestamp in milliseconds
+ */
+export function calculateExpiry(expiresInSeconds, fromTimestamp) {
+    const baseTime = fromTimestamp ?? Date.now();
+    return baseTime + expiresInSeconds * 1000;
+}
+/**
+ * Check if a timestamp is expired
+ *
+ * @param expiryTimestamp - Expiry timestamp in milliseconds
+ * @param bufferSeconds - Optional buffer time in seconds (default: 60)
+ * @returns true if expired (or will expire within buffer time)
+ */
+export function isExpired(expiryTimestamp, bufferSeconds = 60) {
+    const now = Date.now();
+    const buffer = bufferSeconds * 1000;
+    return now + buffer >= expiryTimestamp;
+}
+/**
+ * Get human-readable time remaining until expiry
+ *
+ * @param expiryTimestamp - Expiry timestamp in milliseconds
+ * @returns Human-readable string (e.g., "2 hours 15 minutes")
+ */
+export function getTimeRemaining(expiryTimestamp) {
+    const now = Date.now();
+    const diff = expiryTimestamp - now;
+    if (diff <= 0) {
+        return 'Expired';
+    }
+    const seconds = Math.floor(diff / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0) {
+        const remainingHours = hours % 24;
+        return `${days} day${days > 1 ? 's' : ''}${remainingHours > 0 ? ` ${remainingHours} hour${remainingHours > 1 ? 's' : ''}` : ''}`;
+    }
+    if (hours > 0) {
+        const remainingMinutes = minutes % 60;
+        return `${hours} hour${hours > 1 ? 's' : ''}${remainingMinutes > 0 ? ` ${remainingMinutes} minute${remainingMinutes > 1 ? 's' : ''}` : ''}`;
+    }
+    if (minutes > 0) {
+        const remainingSeconds = seconds % 60;
+        return `${minutes} minute${minutes > 1 ? 's' : ''}${remainingSeconds > 0 ? ` ${remainingSeconds} second${remainingSeconds > 1 ? 's' : ''}` : ''}`;
+    }
+    return `${seconds} second${seconds > 1 ? 's' : ''}`;
+}
+export function validateTokenExpiry(accessTokenExpiry, refreshTokenExpiry) {
+    const warnings = [];
+    const recommendations = [];
+    const accessExpired = isExpired(accessTokenExpiry, 0);
+    const accessExpiringSoon = isExpired(accessTokenExpiry, 300); // 5 minutes
+    const refreshExpired = isExpired(refreshTokenExpiry, 0);
+    const refreshExpiringSoon = isExpired(refreshTokenExpiry, 86400); // 1 day
+    let accessTokenStatus = 'valid';
+    let refreshTokenStatus = 'valid';
+    if (accessExpired) {
+        accessTokenStatus = 'expired';
+        warnings.push('Access token has expired');
+        if (!refreshExpired) {
+            recommendations.push('Use the refresh token to obtain a new access token');
+        }
+    }
+    else if (accessExpiringSoon) {
+        accessTokenStatus = 'expiring-soon';
+        warnings.push('Access token will expire soon');
+    }
+    if (refreshExpired) {
+        refreshTokenStatus = 'expired';
+        warnings.push('Refresh token has expired');
+        recommendations.push('User needs to re-authorize the application to get new tokens');
+    }
+    else if (refreshExpiringSoon) {
+        refreshTokenStatus = 'expiring-soon';
+        warnings.push('Refresh token will expire soon (within 24 hours)');
+        recommendations.push('Consider prompting user to re-authorize before refresh token expires');
+    }
+    return {
+        valid: !accessExpired && !refreshExpired,
+        accessTokenStatus,
+        refreshTokenStatus,
+        accessTokenRemaining: getTimeRemaining(accessTokenExpiry),
+        refreshTokenRemaining: getTimeRemaining(refreshTokenExpiry),
+        warnings,
+        recommendations,
+    };
+}

package/build/utils/llm-client-detector.d.ts

@@ -0,0 +1,54 @@
+/**
+ * LLM Client Detection and Auto-Configuration
+ *
+ * Detects installed LLM clients and provides utilities to auto-configure them
+ * with the eBay MCP server settings.
+ */
+export interface LLMClient {
+    name: string;
+    displayName: string;
+    configPath: string;
+    detected: boolean;
+    configExists: boolean;
+}
+export interface MCPServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Detect all available LLM clients
+ */
+export declare function detectLLMClients(): LLMClient[];
+/**
+ * Configure Claude Desktop with eBay MCP server
+ */
+export declare function configureClaudeDesktop(projectRoot: string): boolean;
+/**
+ * Configure Cline (VSCode extension) with eBay MCP server
+ */
+export declare function configureCline(projectRoot: string): boolean;
+/**
+ * Configure Continue.dev with eBay MCP server
+ */
+export declare function configureContinue(projectRoot: string): boolean;
+/**
+ * Configure specified LLM client
+ */
+export declare function configureLLMClient(clientName: string, projectRoot: string): boolean;
+/**
+ * Get human-readable instructions for manual configuration
+ */
+export declare function getManualConfigInstructions(clientName: string, projectRoot: string): string;
+/**
+ * Verify client configuration is correct
+ */
+export declare function verifyClientConfiguration(clientName: string, projectRoot: string): boolean;
+/**
+ * Get all LLM clients (detected and undetected)
+ */
+export declare function getAllSupportedClients(): string[];
+/**
+ * Check if client supports MCP protocol
+ */
+export declare function supportsNativeMCP(clientName: string): boolean;