ebay-mcp 1.18.3 → 2.0.0

package/build/scripts/devSync.js

@@ -3,13 +3,15 @@ import chalk from 'chalk';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
 import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
+import { execFileSync, execSync } from 'child_process';
 import { Effect, Either } from 'effect';
 import { getErrorMessage } from '../utils/errors.js';
-import { httpRequest } from '../utils/http.js';
 import process from 'node:process';
+import { classifyOperation, collectImplementedNames, normalizeForMatching, } from './specCoverage.js';
+import { refreshCachedSpec } from './specDownload.js';
 import { replaceDanglingSchemaRefs } from './specRefs.js';
-import { specSources } from './specSources.js';
+import { specFileName, specSources } from './specSources.js';
+import { generatedNamespaceNames, renameGeneratedNamespaces } from './specTypeNames.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PROJECT_ROOT = join(__dirname, '../..');
@@ -17,25 +19,6 @@ const PROJECT_ROOT = join(__dirname, '../..');
 const SPECS_DIR = join(PROJECT_ROOT, '.cache/ebay-specs');
 const TYPES_DIR = join(PROJECT_ROOT, 'src/types');
 const TOOLS_DIRS = [join(PROJECT_ROOT, 'src/tools/categories')];
-/** Repo-specific OpenAPI namespace aliases preserved after type regeneration. */
-const GENERATED_TYPE_ALIASES = {
-    developerAnalyticsV1BetaOas3: {
-        components: 'DeveloperAnalyticsComponents',
-        operations: 'DeveloperAnalyticsOperations',
-    },
-    developerClientRegistrationV1Oas3: {
-        components: 'DeveloperClientRegistrationComponents',
-        operations: 'DeveloperClientRegistrationOperations',
-    },
-    developerKeyManagementV1Oas3: {
-        components: 'DeveloperKeyManagementComponents',
-        operations: 'DeveloperKeyManagementOperations',
-    },
-    sellComplianceV1Oas3: {
-        components: 'SellComplianceComponents',
-        operations: 'SellComplianceOperations',
-    },
-};
 const ui = {
     success: chalk.green,
     warning: chalk.yellow,
@@ -44,51 +27,14 @@ const ui = {
     dim: chalk.dim,
     bold: chalk.bold,
 };
-/**
- * Checks whether an openapi-typescript output exposes a generated namespace.
- *
- * @param content - Generated TypeScript declaration content to inspect.
- * @param exportName - Namespace export that must exist before adding an alias.
- * @returns True when the generated output exposes the requested namespace.
- *
- * @example
- * ```ts
- * hasGeneratedExport(content, 'components');
- * ```
- */
-const hasGeneratedExport = (content, exportName) => content.includes(`export interface ${exportName}`) ||
-    content.includes(`export type ${exportName}`);
-/**
- * Appends repo-specific generated type aliases after openapi-typescript rewrites a file.
- *
- * @param outputPath - Generated TypeScript declaration file path.
- * @param camelCaseName - OpenAPI spec basename used as the generated type file name.
- * @returns Nothing; the generated file is updated in place when aliases are needed.
- *
- * @example
- * ```ts
- * preserveGeneratedTypeAliases(outputPath, 'sellComplianceV1Oas3');
- * ```
- */
-const preserveGeneratedTypeAliases = (outputPath, camelCaseName) => {
-    const aliases = GENERATED_TYPE_ALIASES[camelCaseName];
-    if (!aliases) {
-        return;
-    }
-    const content = readFileSync(outputPath, 'utf-8');
-    const aliasLines = [];
-    if (hasGeneratedExport(content, 'components') &&
-        !content.includes(`export type ${aliases.components}`)) {
-        aliasLines.push('/** Repo-specific alias for generated OpenAPI components. */', `export type ${aliases.components} = components;`);
-    }
-    if (hasGeneratedExport(content, 'operations') &&
-        !content.includes(`export type ${aliases.operations}`)) {
-        aliasLines.push('/** Repo-specific alias for generated OpenAPI operations. */', `export type ${aliases.operations} = operations;`);
-    }
-    if (aliasLines.length === 0) {
+const applyNamespaceNames = (outputPath, camelCaseName) => {
+    const names = generatedNamespaceNames[camelCaseName];
+    if (!names) {
         return;
     }
-    writeFileSync(outputPath, `${content.trimEnd()}\n\n${aliasLines.join('\n')}\n`);
+    const generatedTypes = readFileSync(outputPath, 'utf-8');
+    const renamedTypes = renameGeneratedNamespaces(generatedTypes, names);
+    writeFileSync(outputPath, renamedTypes);
 };
 function showSpinner(message) {
     const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
@@ -107,41 +53,33 @@ async function downloadSpecs() {
     console.log(ui.bold('\n📥 Downloading OpenAPI Specifications\n'));
     console.log(ui.dim(`  Found ${specSources.length} spec URLs\n`));
     let downloaded = 0;
-    let failed = 0;
-    for (const { api, folder, url } of specSources) {
-        const fileName = basename(url);
-        const folderPath = join(SPECS_DIR, folder);
-        const filePath = join(folderPath, fileName);
+    const unavailable = [];
+    for (const source of specSources) {
+        const { api, folder, url } = source;
+        const fileName = specFileName(source);
+        const specPath = join(SPECS_DIR, folder, fileName);
         const stopSpinner = showSpinner(`Downloading ${api} (${fileName})...`);
-        const downloadedSpec = await Effect.runPromise(Effect.either(Effect.tryPromise({
-            try: async () => {
-                mkdirSync(folderPath, { recursive: true });
-                const specResponse = await httpRequest({
-                    url,
-                    responseType: 'arraybuffer',
-                    timeoutMs: 20_000,
-                });
-                writeFileSync(filePath, specResponse.data);
-            },
-            catch: (error) => error,
-        }).pipe(Effect.ensuring(Effect.sync(stopSpinner)))));
-        if (Either.isLeft(downloadedSpec)) {
-            console.log(`  ${ui.error('✗')} ${api} (${fileName}): ${getErrorMessage(downloadedSpec.left)}`);
-            failed++;
-        }
-        else {
+        const refresh = refreshCachedSpec(url, specPath).pipe(Effect.either);
+        const refreshOutcome = await Effect.runPromise(refresh);
+        stopSpinner();
+        if (Either.isRight(refreshOutcome)) {
             console.log(`  ${ui.success('✓')} ${api} (${fileName})`);
             downloaded++;
+            continue;
         }
+        const reason = refreshOutcome.left.message;
+        const cacheNote = existsSync(specPath) ? 'kept the cached copy' : 'no cached copy';
+        console.log(`  ${ui.error('✗')} ${api} (${fileName}): unavailable, ${reason}; ${cacheNote}`);
+        unavailable.push({ api, fileName, url, reason });
     }
-    if (failed > 0 && downloaded === 0) {
-        console.log(ui.error(`\n  ✗ All ${failed} spec downloads failed — eBay is likely blocking automated requests (HTTP 403).`));
+    if (unavailable.length > 0 && downloaded === 0) {
+        console.log(ui.error(`\n  ✗ All ${unavailable.length} spec downloads failed — eBay is likely blocking automated requests (HTTP 403).`));
     }
-    return downloaded;
+    return { downloaded, unavailable };
 }
 function generateTypes() {
     console.log(ui.bold('\n🔧 Generating TypeScript Types\n'));
-    let generated = 0;
+    const generatedPaths = [];
     let skipped = 0;
     function processDirectory(dir) {
         if (!existsSync(dir))
@@ -199,9 +137,9 @@ function generateTypes() {
                     catch: (error) => error,
                 })));
                 if (Either.isRight(generatedFile)) {
-                    preserveGeneratedTypeAliases(outputPath, camelCaseName);
+                    applyNamespaceNames(outputPath, camelCaseName);
                     console.log(`  ${ui.success('✓')} ${camelCaseName}.ts`);
-                    generated++;
+                    generatedPaths.push(outputPath);
                 }
                 else {
                     console.log(`  ${ui.error('✗')} ${camelCaseName}.ts (generation failed): ${getErrorMessage(generatedFile.left)}`);
@@ -210,8 +148,15 @@ function generateTypes() {
         }
     }
     processDirectory(SPECS_DIR);
-    console.log(ui.dim(`\n  Generated: ${generated}, Skipped: ${skipped}`));
-    return generated;
+    // Format with the repo's Biome settings so regenerating unchanged specs leaves no diff.
+    if (generatedPaths.length > 0) {
+        execFileSync('npx', ['biome', 'format', '--write', ...generatedPaths], {
+            stdio: 'pipe',
+            cwd: PROJECT_ROOT,
+        });
+    }
+    console.log(ui.dim(`\n  Generated: ${generatedPaths.length}, Skipped: ${skipped}`));
+    return generatedPaths.length;
 }
 function extractEndpointsFromSpecs() {
     const endpoints = [];
@@ -277,69 +222,6 @@ function getImplementedTools() {
     }
     return tools;
 }
-function camelToSnake(str) {
-    return str
-        .replace(/([A-Z])/g, '_$1')
-        .toLowerCase()
-        .replace(/^_/, '');
-}
-function normalizeForMatching(name) {
-    return name.toLowerCase().replace(/[^a-z0-9]/g, '');
-}
-/**
- * Known mappings from OpenAPI operationId to our tool names
- * This handles cases where naming conventions differ significantly
- */
-const KNOWN_OPERATION_MAPPINGS = {
-    // Feedback API
-    getitemsawaitingfeedback: ['ebay_get_awaiting_feedback'],
-    leavefeedback: ['ebay_leave_feedback_for_buyer'],
-    // Notification API — tools use the ebay_*_notification_* naming convention
-    getconfig: ['ebay_get_notification_config'],
-    updateconfig: ['ebay_update_notification_config'],
-    getdestinations: ['ebay_get_notification_destinations'],
-    createdestination: ['ebay_create_notification_destination'],
-    getdestination: ['ebay_get_notification_destination'],
-    updatedestination: ['ebay_update_notification_destination'],
-    deletedestination: ['ebay_delete_notification_destination'],
-    getsubscriptions: ['ebay_get_notification_subscriptions'],
-    createsubscription: ['ebay_create_notification_subscription'],
-    getsubscription: ['ebay_get_notification_subscription'],
-    updatesubscription: ['ebay_update_notification_subscription'],
-    deletesubscription: ['ebay_delete_notification_subscription'],
-    disablesubscription: ['ebay_disable_notification_subscription'],
-    enablesubscription: ['ebay_enable_notification_subscription'],
-    testsubscription: ['ebay_test_notification_subscription'],
-    createsubscriptionfilter: ['ebay_create_notification_subscription_filter'],
-    getsubscriptionfilter: ['ebay_get_notification_subscription_filter'],
-    deletesubscriptionfilter: ['ebay_delete_notification_subscription_filter'],
-    gettopic: ['ebay_get_notification_topic'],
-    gettopics: ['ebay_get_notification_topics'],
-    getpublickey: ['ebay_get_notification_public_key'],
-    // Negotiation API
-    findeligibleitems: ['ebay_find_eligible_items'],
-    // Marketing API
-    createadbylistingid: ['ebay_create_ad_by_listing_id'],
-    updatebid: ['ebay_update_bid'],
-    bulkcreatekeyword: ['ebay_bulk_create_keyword'],
-    bulkupdatekeyword: ['ebay_bulk_update_keyword'],
-    bulkcreatenegativekeyword: ['ebay_bulk_create_negative_keyword'],
-    bulkupdatenegativekeyword: ['ebay_bulk_update_negative_keyword'],
-    getnegativekeywords: ['ebay_get_negative_keywords'],
-    createnegativekeyword: ['ebay_create_negative_keyword'],
-    getnegativekeyword: ['ebay_get_negative_keyword'],
-    updatenegativekeyword: ['ebay_update_negative_keyword'],
-    getreportmetadata: ['ebay_get_report_metadata'],
-    getreportmetadataforreporttype: ['ebay_get_report_metadata_for_report_type'],
-    getpromotionreports: ['ebay_get_promotion_reports'],
-    getaudiences: ['ebay_get_audiences'],
-    // Dispute/Fulfillment API
-    fetchevidencecontent: ['ebay_fetch_evidence_content'],
-    getactivities: ['ebay_get_payment_dispute_activities', 'ebay_get_activities'],
-    uploadevidencefile: ['ebay_upload_evidence_file'],
-    addevidence: ['ebay_add_evidence'],
-    updateevidence: ['ebay_update_evidence'],
-};
 /**
  * Get all implemented API methods from source files
  */
@@ -365,11 +247,11 @@ function getImplementedApiMethods() {
                     // Many area classes omit the `public` keyword (notification, trading, feedback, …).
                     const methodMatches = source.right.matchAll(/(?:async\s+(\w+)\s*\(|(?:public\s+)?(\w+)\s*=\s*(?:async\s*)?\()/g);
                     for (const match of methodMatches) {
-                        const name = match[1] ?? match[2];
+                        const name = match[1] || match[2];
                         // Skip common non-method bindings that the broader regex can catch.
                         if (!name || name === 'const' || name === 'let' || name === 'var')
                             continue;
-                        methods.add(normalizeForMatching(name));
+                        methods.add(name);
                     }
                 }
             }
@@ -378,63 +260,12 @@ function getImplementedApiMethods() {
     processDirectory(apiDir);
     return methods;
 }
-/**
- * Generate all possible name variations for an operationId
- */
-function generateNameVariations(opId) {
-    const variations = [];
-    const normalized = normalizeForMatching(opId);
-    // Direct variations
-    variations.push(normalized);
-    variations.push(`ebay${normalized}`);
-    variations.push(normalizeForMatching(`ebay_${camelToSnake(opId)}`));
-    variations.push(normalizeForMatching(camelToSnake(opId)));
-    // Remove common suffixes/prefixes that might differ
-    const withoutItems = normalized.replace(/items?$/, '');
-    if (withoutItems !== normalized) {
-        variations.push(withoutItems);
-        variations.push(`ebay${withoutItems}`);
-    }
-    // Handle "ByX" patterns -> remove them
-    const withoutBy = normalized.replace(/by\w+$/, '');
-    if (withoutBy !== normalized) {
-        variations.push(withoutBy);
-        variations.push(`ebay${withoutBy}`);
-    }
-    // Handle "ForX" patterns -> remove them
-    const withoutFor = normalized.replace(/for\w+$/, '');
-    if (withoutFor !== normalized) {
-        variations.push(withoutFor);
-        variations.push(`ebay${withoutFor}`);
-    }
-    // Handle plural/singular
-    if (normalized.endsWith('s') && !normalized.endsWith('ss')) {
-        const singular = normalized.slice(0, -1);
-        variations.push(singular);
-        variations.push(`ebay${singular}`);
-    }
-    else {
-        const plural = normalized + 's';
-        variations.push(plural);
-        variations.push(`ebay${plural}`);
-    }
-    // Check known mappings
-    if (KNOWN_OPERATION_MAPPINGS[normalized]) {
-        for (const mapped of KNOWN_OPERATION_MAPPINGS[normalized]) {
-            variations.push(normalizeForMatching(mapped));
-        }
-    }
-    return [...new Set(variations)];
-}
 function analyzeEndpoints() {
     console.log(ui.bold('\n📊 Analyzing API Coverage\n'));
     const specEndpoints = extractEndpointsFromSpecs();
     const implementedTools = getImplementedTools();
     const implementedApiMethods = getImplementedApiMethods();
-    // Normalize all tool names
-    const normalizedTools = new Set(Array.from(implementedTools).map((toolName) => normalizeForMatching(toolName)));
-    // Combine tools and API methods for matching
-    const allImplemented = new Set([...normalizedTools, ...implementedApiMethods]);
+    const implemented = collectImplementedNames([...implementedApiMethods], [...implementedTools]);
     // Track unique endpoints (dedupe by operationId)
     const seenOperationIds = new Set();
     const uniqueEndpoints = [];
@@ -445,31 +276,42 @@ function analyzeEndpoints() {
             uniqueEndpoints.push(endpoint);
         }
     }
+    const fuzzy = [];
     const missing = [];
-    let matchedCount = 0;
+    let exact = 0;
     for (const endpoint of uniqueEndpoints) {
-        const opId = endpoint.operationId;
-        const variations = generateNameVariations(opId);
-        const isImplemented = variations.some((name) => allImplemented.has(name));
-        if (isImplemented) {
-            matchedCount++;
+        const coverage = classifyOperation(endpoint.operationId, implemented);
+        if (coverage === 'exact') {
+            exact++;
+        }
+        else if (coverage === 'fuzzy') {
+            fuzzy.push(endpoint);
         }
         else {
             missing.push(endpoint);
         }
     }
+    const matchedCount = exact + fuzzy.length;
     const coveragePercent = uniqueEndpoints.length > 0 ? ((matchedCount / uniqueEndpoints.length) * 100).toFixed(1) : '0';
     console.log(`  ${ui.info('Total unique endpoints in specs:')} ${uniqueEndpoints.length}`);
     console.log(`  ${ui.info('(Raw count with duplicates:')} ${specEndpoints.length}${ui.info(')')}`);
     console.log(`  ${ui.success('Tools implemented:')} ${implementedTools.size}`);
     console.log(`  ${ui.success('API methods found:')} ${implementedApiMethods.size}`);
     console.log(`  ${ui.success('Endpoints covered:')} ${matchedCount} (${coveragePercent}%)`);
+    console.log(`    ${ui.success('Exact operationId matches:')} ${exact}`);
+    console.log(`    ${ui.warning('Fuzzy-only matches:')} ${fuzzy.length}`);
     console.log(`  ${ui.warning('Potentially missing:')} ${missing.length}`);
-    return {
-        total: uniqueEndpoints.length,
-        implemented: matchedCount,
-        missing,
-    };
+    return { total: uniqueEndpoints.length, exact, fuzzy, missing };
+}
+function showFuzzyMatches(fuzzy) {
+    if (fuzzy.length === 0) {
+        return;
+    }
+    console.log(ui.bold('\nFuzzy-only Matches\n'));
+    console.log(ui.dim('  No API method carries these operationIds exactly; a looser name matched:\n'));
+    for (const ep of fuzzy) {
+        console.log(`    ${ui.dim(ep.method.padEnd(6))} ${ep.path} ${ui.dim(`(${ep.operationId})`)}`);
+    }
 }
 function showMissingEndpoints(missing) {
     if (missing.length === 0) {
@@ -539,13 +381,18 @@ ${ui.bold('What this does:')}
     }
     const report = {
         specsDownloaded: 0,
+        unavailableSpecs: [],
         typesGenerated: 0,
         endpointsInSpecs: 0,
         toolsImplemented: 0,
+        exactMatches: 0,
+        fuzzyMatchedEndpoints: [],
         missingEndpoints: [],
     };
     if (!(reportOnly || skipDownload)) {
-        report.specsDownloaded = await downloadSpecs();
+        const downloads = await downloadSpecs();
+        report.specsDownloaded = downloads.downloaded;
+        report.unavailableSpecs = downloads.unavailable;
     }
     // If the download step ran but fetched nothing (for example, blocked
     // requests), the coverage numbers below describe the cached specs on disk —
@@ -561,8 +408,11 @@ ${ui.bold('What this does:')}
     }
     const analysis = analyzeEndpoints();
     report.endpointsInSpecs = analysis.total;
-    report.toolsImplemented = analysis.implemented;
+    report.toolsImplemented = analysis.exact + analysis.fuzzy.length;
+    report.exactMatches = analysis.exact;
+    report.fuzzyMatchedEndpoints = analysis.fuzzy;
     report.missingEndpoints = analysis.missing;
+    showFuzzyMatches(analysis.fuzzy);
     showMissingEndpoints(analysis.missing);
     generateReport(report);
     if (usingStaleSpecs) {

package/build/scripts/specCoverage.js

@@ -0,0 +1,78 @@
+const KNOWN_OPERATION_MAPPINGS = {
+    // Notification API — tools use the ebay_*_notification_* naming convention
+    getconfig: ['ebay_get_notification_config'],
+    updateconfig: ['ebay_update_notification_config'],
+    getdestinations: ['ebay_get_notification_destinations'],
+    createdestination: ['ebay_create_notification_destination'],
+    getdestination: ['ebay_get_notification_destination'],
+    updatedestination: ['ebay_update_notification_destination'],
+    deletedestination: ['ebay_delete_notification_destination'],
+    getsubscriptions: ['ebay_get_notification_subscriptions'],
+    createsubscription: ['ebay_create_notification_subscription'],
+    getsubscription: ['ebay_get_notification_subscription'],
+    updatesubscription: ['ebay_update_notification_subscription'],
+    deletesubscription: ['ebay_delete_notification_subscription'],
+    disablesubscription: ['ebay_disable_notification_subscription'],
+    enablesubscription: ['ebay_enable_notification_subscription'],
+    testsubscription: ['ebay_test_notification_subscription'],
+    createsubscriptionfilter: ['ebay_create_notification_subscription_filter'],
+    getsubscriptionfilter: ['ebay_get_notification_subscription_filter'],
+    deletesubscriptionfilter: ['ebay_delete_notification_subscription_filter'],
+    gettopic: ['ebay_get_notification_topic'],
+    gettopics: ['ebay_get_notification_topics'],
+    getpublickey: ['ebay_get_notification_public_key'],
+    // Negotiation API
+    findeligibleitems: ['ebay_find_eligible_items'],
+    // Marketing API
+    createadbylistingid: ['ebay_create_ad_by_listing_id'],
+    updatebid: ['ebay_update_bid'],
+    bulkcreatekeyword: ['ebay_bulk_create_keyword'],
+    bulkupdatekeyword: ['ebay_bulk_update_keyword'],
+    bulkcreatenegativekeyword: ['ebay_bulk_create_negative_keyword'],
+    bulkupdatenegativekeyword: ['ebay_bulk_update_negative_keyword'],
+    getnegativekeywords: ['ebay_get_negative_keywords'],
+    createnegativekeyword: ['ebay_create_negative_keyword'],
+    getnegativekeyword: ['ebay_get_negative_keyword'],
+    updatenegativekeyword: ['ebay_update_negative_keyword'],
+    getreportmetadata: ['ebay_get_report_metadata'],
+    getreportmetadataforreporttype: ['ebay_get_report_metadata_for_report_type'],
+    getpromotionreports: ['ebay_get_promotion_reports'],
+    getaudiences: ['ebay_get_audiences'],
+    // Dispute/Fulfillment API
+    fetchevidencecontent: ['ebay_fetch_evidence_content'],
+    getactivities: ['ebay_get_payment_dispute_activities', 'ebay_get_activities'],
+    uploadevidencefile: ['ebay_upload_evidence_file'],
+    addevidence: ['ebay_add_evidence'],
+    updateevidence: ['ebay_update_evidence'],
+};
+const ITEMS_SUFFIX = /items?$/;
+const BY_SUFFIX = /by\w+$/;
+const FOR_SUFFIX = /for\w+$/;
+const singularOrPlural = (name) => name.endsWith('s') && !name.endsWith('ss') ? name.slice(0, -1) : `${name}s`;
+const fuzzyNameVariations = (operationId) => {
+    const normalized = normalizeForMatching(operationId);
+    const stems = [
+        normalized,
+        normalized.replace(ITEMS_SUFFIX, ''),
+        normalized.replace(BY_SUFFIX, ''),
+        normalized.replace(FOR_SUFFIX, ''),
+        singularOrPlural(normalized),
+    ];
+    const prefixedStems = stems.map((stem) => `ebay${stem}`);
+    const mappedTools = KNOWN_OPERATION_MAPPINGS[normalized] || [];
+    const mappedNames = mappedTools.map(normalizeForMatching);
+    return new Set([...stems, ...prefixedStems, ...mappedNames]);
+};
+export const normalizeForMatching = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+export const collectImplementedNames = (apiMethods, toolNames) => {
+    const normalizedNames = [...apiMethods, ...toolNames].map(normalizeForMatching);
+    return { apiMethods: new Set(apiMethods), normalizedNames: new Set(normalizedNames) };
+};
+export const classifyOperation = (operationId, implemented) => {
+    if (implemented.apiMethods.has(operationId)) {
+        return 'exact';
+    }
+    const variations = fuzzyNameVariations(operationId);
+    const hasFuzzyMatch = [...variations].some((name) => implemented.normalizedNames.has(name));
+    return hasFuzzyMatch ? 'fuzzy' : 'missing';
+};

package/build/scripts/specDownload.js

@@ -0,0 +1,42 @@
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { Data, Effect } from 'effect';
+import { getErrorMessage } from '../utils/errors.js';
+import { httpRequestEffect } from '../utils/http.js';
+const isVersionText = (version) => typeof version === 'string' && version.trim() !== '';
+const hasSpecVersion = (spec) => spec !== null &&
+    typeof spec === 'object' &&
+    (('openapi' in spec && isVersionText(spec.openapi)) ||
+        ('swagger' in spec && isVersionText(spec.swagger)));
+export class UnusableSpecError extends Data.TaggedError('UnusableSpecError') {
+}
+export class SpecCacheWriteError extends Data.TaggedError('SpecCacheWriteError') {
+}
+export const checkSpecDownload = (specBytes) => {
+    const specText = specBytes.toString('utf-8');
+    if (specText.trim() === '') {
+        return Effect.fail(new UnusableSpecError({ message: 'empty response' }));
+    }
+    return Effect.try({
+        try: () => JSON.parse(specText),
+        catch: () => new UnusableSpecError({ message: 'response is not JSON' }),
+    }).pipe(Effect.filterOrFail(hasSpecVersion, () => new UnusableSpecError({ message: 'JSON has no openapi or swagger version' })), Effect.as(specBytes));
+};
+export const refreshCachedSpec = (url, specPath) => httpRequestEffect({ url, responseType: 'arraybuffer', timeoutMs: 20_000 }).pipe(Effect.flatMap((specResponse) => checkSpecDownload(specResponse.data)), Effect.flatMap((specBytes) => {
+    // Write beside the cache, then rename, so a failed write never truncates the cached spec.
+    const downloadPath = `${specPath}.download`;
+    return Effect.try({
+        try: () => {
+            mkdirSync(dirname(specPath), { recursive: true });
+            writeFileSync(downloadPath, specBytes);
+            renameSync(downloadPath, specPath);
+        },
+        catch: (error) => {
+            rmSync(downloadPath, { force: true });
+            return new SpecCacheWriteError({
+                specPath,
+                message: getErrorMessage(error, 'write failed'),
+            });
+        },
+    });
+}));

package/build/scripts/specRefs.js

@@ -14,9 +14,8 @@ const definedSchemaNames = (spec) => {
 /**
  * Replaces references to component schemas the spec never defines with an open schema.
  *
- * eBay occasionally publishes a spec with a dangling `$ref` (Account v2 references
- * `SetUserPreferencesRequest` without defining it), and openapi-typescript aborts the
- * whole file on the first unresolved reference. Rewriting only the dangling references
+ * eBay occasionally publishes a spec with a dangling `$ref`, and openapi-typescript
+ * aborts the whole file on the first unresolved reference. Rewriting only the dangling references
  * keeps every defined type exact, while the undefined payload generates as `unknown`
  * with a description naming the missing schema.
  *

package/build/scripts/specSources.js

@@ -4,6 +4,8 @@
  * Each spec lands in `.cache/ebay-specs/<folder>/`, and its generated types land in
  * `src/types/<folder>/`, so `folder` must match the existing generated-type layout.
  */
+import { basename } from 'node:path';
+export const specFileName = ({ url, fileName }) => fileName || basename(url);
 /** Every spec `pnpm sync` downloads, grouped the same way as `src/types/`. */
 export const specSources = [
     {
@@ -64,7 +66,8 @@ export const specSources = [
     {
         api: 'Account API (v2)',
         folder: 'sell-apps/account-management',
-        url: 'https://developer.ebay.com/api-docs/master/sell/account/v2/openapi/3/sell_account_v2_oas3.json',
+        url: 'https://developer.ebay.com/develop/api/spec/account_api_v2.json',
+        fileName: 'sell_account_v2_oas3.json',
     },
     {
         api: 'Finances API',
@@ -121,11 +124,6 @@ export const specSources = [
         folder: 'sell-apps/other-apis',
         url: 'https://developer.ebay.com/api-docs/master/commerce/translation/openapi/3/commerce_translation_v1_beta_oas3.json',
     },
-    {
-        api: 'Compliance API',
-        folder: 'sell-apps/other-apis',
-        url: 'https://developer.ebay.com/api-docs/master/sell/compliance/openapi/3/sell_compliance_v1_oas3.json',
-    },
     {
         api: 'Identity API',
         folder: 'sell-apps/other-apis',

package/build/scripts/specTypeNames.js

@@ -0,0 +1,23 @@
+const COMPONENTS_DECLARATION = /\binterface components\b/g;
+const COMPONENTS_REFERENCE = /\bcomponents\[/g;
+const OPERATIONS_DECLARATION = /\binterface operations\b/g;
+const OPERATIONS_REFERENCE = /\boperations\[/g;
+export const generatedNamespaceNames = {
+    developerAnalyticsV1BetaOas3: {
+        components: 'DeveloperAnalyticsComponents',
+        operations: 'DeveloperAnalyticsOperations',
+    },
+    developerClientRegistrationV1Oas3: {
+        components: 'DeveloperClientRegistrationComponents',
+        operations: 'DeveloperClientRegistrationOperations',
+    },
+    developerKeyManagementV1Oas3: {
+        components: 'DeveloperKeyManagementComponents',
+        operations: 'DeveloperKeyManagementOperations',
+    },
+};
+export const renameGeneratedNamespaces = (generatedTypes, names) => generatedTypes
+    .replace(COMPONENTS_DECLARATION, `interface ${names.components}`)
+    .replace(COMPONENTS_REFERENCE, `${names.components}[`)
+    .replace(OPERATIONS_DECLARATION, `interface ${names.operations}`)
+    .replace(OPERATIONS_REFERENCE, `${names.operations}[`);

package/build/skills/content.js

@@ -24,7 +24,7 @@ export const buildUsingDoc = (snapshot) => ({
     slug: 'ebay-mcp-using',
     title: 'Using the eBay MCP tools',
     description: `Drive eBay's Sell APIs through the ebay-mcp server: ${snapshot.toolCount} tools for listings, orders, marketing, and analytics. Use when creating or revising listings, fulfilling orders, issuing refunds, running Promoted Listings campaigns, or debugging eBay auth/rate-limit errors.`,
-    intro: `The \`ebay-mcp\` server exposes **${snapshot.toolCount} tools across 100% of eBay's Sell APIs**, running locally over MCP. Every tool is named \`ebay_<verb>_<noun>\` (plus two ChatGPT-connector tools, \`search\`/\`fetch\`). You already see each tool's input schema via \`tools/list\` — this skill covers what discovery can't: which tools to chain, what eBay requires first, and how to read its errors.`,
+    intro: `The \`ebay-mcp\` server exposes **${snapshot.toolCount} tools covering 100% of the eBay Sell, Commerce and Developer APIs it tracks**, running locally over MCP. Every tool is named \`ebay_<verb>_<noun>\` (plus two ChatGPT-connector tools, \`search\`/\`fetch\`). You already see each tool's input schema via \`tools/list\` — this skill covers what discovery can't: which tools to chain, what eBay requires first, and how to read its errors.`,
     sections: [
         {
             heading: 'Authentication & environment',
@@ -102,7 +102,7 @@ export const buildContributingDoc = (snapshot) => ({
     slug: 'ebay-mcp-contributing',
     title: 'Contributing to ebay-mcp',
     description: `Work on the ebay-mcp server itself: ${snapshot.toolCount} tools across eBay's Sell APIs (TypeScript/ESM, Zod tool-input schemas, OpenAPI-generated types). Use when adding or changing eBay tools/endpoints, wiring the registry, or running the project's checks.`,
-    intro: `A local MCP server exposing **${snapshot.toolCount} tools across 100% of eBay's Sell APIs** — TypeScript/Node.js (ESM), \`@modelcontextprotocol/sdk\`, Zod tool-input schemas, Effect for typed async errors, OpenAPI-generated types. Entry points: \`src/index.ts\` (STDIO) and \`src/serverHttp.ts\` (HTTP).`,
+    intro: `A local MCP server exposing **${snapshot.toolCount} tools covering 100% of the eBay Sell, Commerce and Developer APIs it tracks** — TypeScript/Node.js (ESM), \`@modelcontextprotocol/sdk\`, Zod tool-input schemas, Effect for typed async errors, OpenAPI-generated types. Entry points: \`src/index.ts\` (STDIO) and \`src/serverHttp.ts\` (HTTP).`,
     sections: [
         {
             heading: 'Validation (run before a PR)',