ebay-mcp 1.4.3

package/build/api/other/identity.d.ts

@@ -0,0 +1,17 @@
+import type { EbayApiClient } from '../client.js';
+/**
+ * Identity API - User identity verification
+ * Based on: docs/sell-apps/other-apis/commerce_identity_v1_oas3.json
+ *
+ * Note: Identity API uses apiz subdomain instead of api
+ */
+export declare class IdentityApi {
+    private client;
+    private readonly basePath;
+    constructor(client: EbayApiClient);
+    /**
+     * Get user information
+     * Uses apiz.ebay.com instead of api.ebay.com
+     */
+    getUser(): Promise<unknown>;
+}

package/build/api/other/identity.js

@@ -0,0 +1,24 @@
+import { getIdentityBaseUrl } from '../../config/environment.js';
+/**
+ * Identity API - User identity verification
+ * Based on: docs/sell-apps/other-apis/commerce_identity_v1_oas3.json
+ *
+ * Note: Identity API uses apiz subdomain instead of api
+ */
+export class IdentityApi {
+    client;
+    basePath = '/commerce/identity/v1';
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get user information
+     * Uses apiz.ebay.com instead of api.ebay.com
+     */
+    async getUser() {
+        const config = this.client.getConfig();
+        const identityBaseUrl = getIdentityBaseUrl(config.environment);
+        const fullUrl = `${identityBaseUrl}${this.basePath}/user`;
+        return await this.client.getWithFullUrl(fullUrl);
+    }
+}

package/build/api/other/translation.d.ts

@@ -0,0 +1,14 @@
+import type { EbayApiClient } from '../../api/client.js';
+/**
+ * Translation API - Translation services
+ * Based on: docs/sell-apps/other-apis/commerce_translation_v1_beta_oas3.json
+ */
+export declare class TranslationApi {
+    private client;
+    private readonly basePath;
+    constructor(client: EbayApiClient);
+    /**
+     * Translate listing text
+     */
+    translate(from: string, to: string, translationContext: string, text: string[]): Promise<unknown>;
+}

package/build/api/other/translation.js

@@ -0,0 +1,22 @@
+/**
+ * Translation API - Translation services
+ * Based on: docs/sell-apps/other-apis/commerce_translation_v1_beta_oas3.json
+ */
+export class TranslationApi {
+    client;
+    basePath = '/commerce/translation/v1';
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Translate listing text
+     */
+    async translate(from, to, translationContext, text) {
+        return await this.client.post(`${this.basePath}/translate`, {
+            from,
+            to,
+            translationContext,
+            text,
+        });
+    }
+}

package/build/api/other/vero.d.ts

@@ -0,0 +1,30 @@
+import type { EbayApiClient } from '../client.js';
+/**
+ * VERO API - Verified Rights Owner program
+ * Based on: docs/sell-apps/other-apis/commerce_vero_v1_oas3.json
+ */
+export declare class VeroApi {
+    private client;
+    private readonly basePath;
+    constructor(client: EbayApiClient);
+    /**
+     * Create a VERO report to report intellectual property infringement
+     */
+    createVeroReport(reportData: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Get a specific VERO report by ID
+     */
+    getVeroReport(veroReportId: string): Promise<unknown>;
+    /**
+     * Get VERO report items (listings reported for infringement)
+     */
+    getVeroReportItems(filter?: string, limit?: number, offset?: number): Promise<unknown>;
+    /**
+     * Get a specific VERO reason code by ID
+     */
+    getVeroReasonCode(veroReasonCodeId: string): Promise<unknown>;
+    /**
+     * Get all available VERO reason codes
+     */
+    getVeroReasonCodes(): Promise<unknown>;
+}

package/build/api/other/vero.js

@@ -0,0 +1,48 @@
+/**
+ * VERO API - Verified Rights Owner program
+ * Based on: docs/sell-apps/other-apis/commerce_vero_v1_oas3.json
+ */
+export class VeroApi {
+    client;
+    basePath = '/commerce/vero/v1';
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Create a VERO report to report intellectual property infringement
+     */
+    async createVeroReport(reportData) {
+        return await this.client.post(`${this.basePath}/vero_report`, reportData);
+    }
+    /**
+     * Get a specific VERO report by ID
+     */
+    async getVeroReport(veroReportId) {
+        return await this.client.get(`${this.basePath}/vero_report/${veroReportId}`);
+    }
+    /**
+     * Get VERO report items (listings reported for infringement)
+     */
+    async getVeroReportItems(filter, limit, offset) {
+        const params = {};
+        if (filter)
+            params.filter = filter;
+        if (limit)
+            params.limit = limit;
+        if (offset)
+            params.offset = offset;
+        return await this.client.get(`${this.basePath}/vero_report_items`, params);
+    }
+    /**
+     * Get a specific VERO reason code by ID
+     */
+    async getVeroReasonCode(veroReasonCodeId) {
+        return await this.client.get(`${this.basePath}/vero_reason_code/${veroReasonCodeId}`);
+    }
+    /**
+     * Get all available VERO reason codes
+     */
+    async getVeroReasonCodes() {
+        return await this.client.get(`${this.basePath}/vero_reason_code`);
+    }
+}

package/build/auth/oauth-metadata.d.ts

@@ -0,0 +1,46 @@
+/**
+ * OAuth metadata endpoints for MCP server
+ * Implements RFC 9728 Protected Resource Metadata
+ */
+import type { Router } from 'express';
+import type { OAuthServerMetadata } from './oauth-types.js';
+export interface MetadataConfig {
+    /**
+     * Resource server URL (e.g., "http://localhost:3000")
+     */
+    resourceServerUrl: string;
+    /**
+     * Authorization server URL or metadata
+     */
+    authServerMetadata: string | OAuthServerMetadata;
+    /**
+     * Scopes supported by this resource server
+     */
+    scopesSupported: string[];
+    /**
+     * Optional documentation URL for this resource server
+     */
+    resourceDocumentation?: string;
+    /**
+     * Resource name for display purposes
+     */
+    resourceName?: string;
+    /**
+     * eBay environment (production or sandbox) - optional
+     * Used to indicate which eBay environment the server is configured for
+     */
+    ebayEnvironment?: 'production' | 'sandbox';
+    /**
+     * eBay-specific OAuth scopes - optional
+     * Separate from MCP OAuth scopes, indicates what eBay API access is available
+     */
+    ebayScopes?: string[];
+}
+/**
+ * Create Express router with OAuth metadata endpoints
+ */
+export declare function createMetadataRouter(config: MetadataConfig): Router;
+/**
+ * Helper to get Protected Resource Metadata URL from server URL
+ */
+export declare function getProtectedResourceMetadataUrl(serverUrl: string): string;

package/build/auth/oauth-metadata.js

@@ -0,0 +1,59 @@
+/**
+ * OAuth metadata endpoints for MCP server
+ * Implements RFC 9728 Protected Resource Metadata
+ */
+import { Router as createRouter } from 'express';
+/**
+ * Create Express router with OAuth metadata endpoints
+ */
+export function createMetadataRouter(config) {
+    const router = createRouter();
+    // RFC 9728: Protected Resource Metadata endpoint
+    // Path: /.well-known/oauth-protected-resource
+    router.get('/.well-known/oauth-protected-resource', (req, res) => {
+        const authServers = typeof config.authServerMetadata === 'string'
+            ? [config.authServerMetadata]
+            : [config.authServerMetadata.issuer];
+        const metadata = {
+            resource: config.resourceServerUrl,
+            authorization_servers: authServers,
+            scopes_supported: config.scopesSupported,
+        };
+        if (config.resourceDocumentation) {
+            metadata.resource_documentation = config.resourceDocumentation;
+        }
+        res.json(metadata);
+    });
+    // Optional: Server info endpoint for debugging
+    router.get('/.well-known/mcp-server-info', (req, res) => {
+        const serverInfo = {
+            name: config.resourceName || 'MCP Resource Server',
+            version: '1.0.0',
+            resource_url: config.resourceServerUrl,
+            authorization_required: true,
+            scopes_supported: config.scopesSupported,
+            documentation: config.resourceDocumentation,
+        };
+        // Add eBay-specific information if provided
+        if (config.ebayEnvironment) {
+            serverInfo.ebay = {
+                environment: config.ebayEnvironment,
+                base_url: config.ebayEnvironment === 'production'
+                    ? 'https://api.ebay.com'
+                    : 'https://api.sandbox.ebay.com',
+                scopes: config.ebayScopes || [],
+                note: 'MCP OAuth scopes (scopes_supported) are separate from eBay API OAuth scopes (ebay.scopes)',
+            };
+        }
+        res.json(serverInfo);
+    });
+    return router;
+}
+/**
+ * Helper to get Protected Resource Metadata URL from server URL
+ */
+export function getProtectedResourceMetadataUrl(serverUrl) {
+    const url = new URL(serverUrl);
+    url.pathname = '/.well-known/oauth-protected-resource';
+    return url.toString();
+}

package/build/auth/oauth-middleware.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OAuth 2.1 middleware for Express
+ * Implements RFC 6750 Bearer Token authentication
+ */
+import type { Request, Response, NextFunction } from 'express';
+import type { TokenVerifier } from './token-verifier.js';
+import type { VerifiedToken } from './oauth-types.js';
+/**
+ * Extended Express Request with verified token
+ */
+export interface AuthenticatedRequest extends Request {
+    auth?: VerifiedToken;
+}
+export interface BearerAuthMiddlewareConfig {
+    /**
+     * Token verifier instance
+     */
+    verifier: TokenVerifier;
+    /**
+     * Protected Resource Metadata URL for WWW-Authenticate header
+     */
+    resourceMetadataUrl: string;
+    /**
+     * Realm for WWW-Authenticate header
+     */
+    realm?: string;
+}
+/**
+ * Create Bearer token authentication middleware
+ */
+export declare function createBearerAuthMiddleware(config: BearerAuthMiddlewareConfig): (req: AuthenticatedRequest, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Optional middleware to check specific scopes
+ */
+export declare function requireScopes(requiredScopes: string[]): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;

package/build/auth/oauth-middleware.js

@@ -0,0 +1,99 @@
+/**
+ * OAuth 2.1 middleware for Express
+ * Implements RFC 6750 Bearer Token authentication
+ */
+/**
+ * Create Bearer token authentication middleware
+ */
+export function createBearerAuthMiddleware(config) {
+    const realm = config.realm || 'mcp';
+    return async (req, res, next) => {
+        try {
+            // Extract token from Authorization header
+            const authHeader = req.headers.authorization;
+            if (!authHeader) {
+                sendUnauthorized(res, realm, config.resourceMetadataUrl, {
+                    error: 'invalid_token',
+                    error_description: 'No authorization header provided',
+                });
+                return;
+            }
+            // Check Bearer scheme
+            const parts = authHeader.split(' ');
+            if (parts.length !== 2 || parts[0] !== 'Bearer') {
+                sendUnauthorized(res, realm, config.resourceMetadataUrl, {
+                    error: 'invalid_token',
+                    error_description: 'Invalid authorization header format. Expected: Bearer <token>',
+                });
+                return;
+            }
+            const token = parts[1];
+            // Verify token
+            try {
+                const verifiedToken = await config.verifier.verifyToken(token);
+                req.auth = verifiedToken;
+                next();
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : 'Token verification failed';
+                sendUnauthorized(res, realm, config.resourceMetadataUrl, {
+                    error: 'invalid_token',
+                    error_description: errorMessage,
+                });
+            }
+        }
+        catch (error) {
+            console.error('OAuth middleware error:', error);
+            res.status(500).json({
+                error: 'server_error',
+                error_description: 'Internal server error during authentication',
+            });
+        }
+    };
+}
+/**
+ * Send 401 Unauthorized response with RFC 6750 compliant WWW-Authenticate header
+ */
+function sendUnauthorized(res, realm, resourceMetadataUrl, challenge) {
+    // Build WWW-Authenticate header per RFC 6750
+    let authenticateValue = `Bearer realm="${realm}", resource_metadata="${resourceMetadataUrl}"`;
+    if (challenge.error) {
+        authenticateValue += `, error="${challenge.error}"`;
+    }
+    if (challenge.error_description) {
+        authenticateValue += `, error_description="${challenge.error_description}"`;
+    }
+    if (challenge.scope) {
+        authenticateValue += `, scope="${challenge.scope}"`;
+    }
+    res.setHeader('WWW-Authenticate', authenticateValue);
+    res.status(401).json({
+        error: challenge.error || 'unauthorized',
+        error_description: challenge.error_description || 'Authorization required',
+    });
+}
+/**
+ * Optional middleware to check specific scopes
+ */
+export function requireScopes(requiredScopes) {
+    return (req, res, next) => {
+        if (!req.auth) {
+            res.status(401).json({
+                error: 'unauthorized',
+                error_description: 'No authentication information found',
+            });
+            return;
+        }
+        const hasRequiredScopes = requiredScopes.every((scope) => req.auth.scopes.includes(scope));
+        if (!hasRequiredScopes) {
+            res.status(403).json({
+                error: 'insufficient_scope',
+                error_description: `Missing required scopes: ${requiredScopes.join(', ')}`,
+                required_scopes: requiredScopes,
+                provided_scopes: req.auth.scopes,
+            });
+            return;
+        }
+        next();
+    };
+}

package/build/auth/oauth-types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * OAuth 2.1 types for MCP server authorization
+ */
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414)
+ */
+export interface OAuthServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    jwks_uri?: string;
+    introspection_endpoint?: string;
+    response_types_supported: string[];
+    grant_types_supported?: string[];
+    token_endpoint_auth_methods_supported?: string[];
+    scopes_supported?: string[];
+    code_challenge_methods_supported?: string[];
+}
+/**
+ * Protected Resource Metadata (RFC 9728)
+ */
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported?: string[];
+    resource_documentation?: string;
+    resource_signing_alg_values_supported?: string[];
+}
+/**
+ * Verified access token payload
+ */
+export interface VerifiedToken {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt?: number;
+    audience?: string | string[];
+    subject?: string;
+}
+/**
+ * Token introspection request (RFC 7662)
+ */
+export interface TokenIntrospectionRequest {
+    token: string;
+    token_type_hint?: 'access_token' | 'refresh_token';
+    client_id?: string;
+    client_secret?: string;
+}
+/**
+ * Token introspection response (RFC 7662)
+ */
+export interface TokenIntrospectionResponse {
+    active: boolean;
+    scope?: string;
+    client_id?: string;
+    username?: string;
+    token_type?: string;
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    sub?: string;
+    aud?: string | string[];
+    iss?: string;
+    jti?: string;
+}

package/build/auth/oauth-types.js

@@ -0,0 +1,4 @@
+/**
+ * OAuth 2.1 types for MCP server authorization
+ */
+export {};

package/build/auth/oauth.d.ts

@@ -0,0 +1,93 @@
+import type { EbayConfig, EbayUserToken, StoredTokenData } from '../types/ebay.js';
+/**
+ * Manages eBay OAuth 2.0 authentication
+ * Loads tokens exclusively from environment variables (.env file)
+ * Supports both client credentials (app tokens) and user access tokens with refresh
+ */
+export declare class EbayOAuthClient {
+    private config;
+    private appAccessToken;
+    private appAccessTokenExpiry;
+    private userTokens;
+    constructor(config: EbayConfig);
+    /**
+     * Initialize user tokens from environment variables only
+     * If EBAY_USER_REFRESH_TOKEN exists, automatically refresh to get a valid access token
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if user tokens are available
+     */
+    hasUserTokens(): boolean;
+    /**
+     * Check if user access token is expired
+     */
+    private isUserAccessTokenExpired;
+    /**
+     * Check if user refresh token is expired
+     */
+    private isUserRefreshTokenExpired;
+    /**
+     * Get a valid access token, with priority order:
+     * 1. User access token (if available and valid, or refreshable)
+     * 2. App access token from client credentials (fallback)
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Set user access token and refresh token
+     * Stores tokens in memory and updates .env file for persistence
+     */
+    setUserTokens(accessToken: string, refreshToken: string, accessTokenExpiry?: number, refreshTokenExpiry?: number): void;
+    /**
+     * Get or refresh the app access token using the client credentials flow.
+     * This method ensures that a valid app access token is always available.
+     * Rate limit: 1,000 requests/day
+     */
+    getOrRefreshAppAccessToken(): Promise<string>;
+    /**
+     * Exchange authorization code for user access token
+     * Note: After receiving tokens, manually add EBAY_USER_REFRESH_TOKEN to .env file
+     */
+    exchangeCodeForToken(code: string): Promise<EbayUserToken>;
+    /**
+     * Refresh user access token using refresh token from .env
+     * This method is public and can be called by LLMs when encountering authentication errors
+     */
+    refreshUserToken(): Promise<void>;
+    /**
+     * Check if currently authenticated (either user or app credentials)
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Clear all authentication tokens from memory
+     * Note: To persist this change, remove EBAY_USER_REFRESH_TOKEN from .env
+     */
+    clearAllTokens(): void;
+    /**
+     * Get current token info for debugging
+     */
+    getTokenInfo(): {
+        hasUserToken: boolean;
+        hasAppAccessToken: boolean;
+        scopeInfo?: {
+            tokenScopes: string[];
+            environmentScopes: string[];
+            missingScopes: string[];
+        };
+    };
+    /**
+     * Get internal user tokens (for debugging/status tools)
+     * @internal
+     */
+    getUserTokens(): StoredTokenData | null;
+    /**
+     * Get internal app access token cached value (for debugging/status tools)
+     * @internal
+     */
+    getCachedAppAccessToken(): string | null;
+    /**
+     * Get internal app access token expiry (for debugging/status tools)
+     * @internal
+     */
+    getCachedAppAccessTokenExpiry(): number;
+}