ebay-mcp-remote-edition 4.6.0 → 4.7.0

package/README.md

@@ -54,7 +54,7 @@ This is an open-source project provided "as is" without warranty of any kind. No
 | Mode | Command | Transport | Best for | Authorization model |
 |------|---------|-----------|----------|---------------------|
 | **Local STDIO** | `pnpm start` / `pnpm run dev` | stdin/stdout | Single-user local AI client (Claude Desktop, Cline, Cursor, etc.) | The local process reads eBay credentials and optional `EBAY_USER_REFRESH_TOKEN` from environment variables. |
-| **Hosted HTTP** | `pnpm run start:http` / `pnpm run dev:http` | Streamable HTTP | Multi-user server deployment; remote MCP clients | Users normally authorize through the browser OAuth flow and then call MCP with `Authorization: Bearer <session-token>`. |
+| **Hosted HTTP** | `pnpm run start:http` / `pnpm run dev:http` | Streamable HTTP | Multi-user server deployment; remote MCP clients | Users authorize through browser OAuth. Requests can use normal session Bearer auth or opt into server-request auth with `X-Ebay-Server-Request: true`. |
 
 Both modes use the same eBay tool registry. Local STDIO is best when one trusted local client owns the eBay credentials. Hosted HTTP runs an Express server with OAuth 2.1 discovery, environment-scoped route trees, server-side token/session storage, and admin-only operational endpoints.
 
@@ -278,9 +278,16 @@ QSTASH_CURRENT_SIGNING_KEY=
 QSTASH_NEXT_SIGNING_KEY=
 EBAY_RESEARCH_SESSION_ALERTS_ENABLED=true
 EBAY_RESEARCH_SESSION_ALERT_CALLBACK_URL=
+
+# eBay Research/Terapeak first-party session source.
+# Set this explicitly in hosted deployments. If unset, research sessions default
+# to Cloudflare KV even when EBAY_TOKEN_STORE_BACKEND=upstash-redis.
+EBAY_RESEARCH_SESSION_STORE=upstash-redis # cloudflare_kv | upstash-redis | filesystem | none
+EBAY_RESEARCH_SESSION_ALLOW_FILESYSTEM_FALLBACK=false
 ```
 
 > `EBAY_TOKEN_STORE_BACKEND` defaults to Cloudflare KV when unset or unrecognized. Use `memory` only for tests or throwaway local development because hosted sessions and tokens are lost on restart.
+> `EBAY_RESEARCH_SESSION_STORE` is separate from OAuth token storage. Set it to `upstash-redis` when Terapeak/eBay Research cookies are stored in Upstash.
 
 ### Secret file
 
@@ -321,7 +328,15 @@ GET /production/oauth/start   # production browser login
 
 If `OAUTH_START_KEY` is set, start URLs require either `?key=YOUR_KEY` or the `X-OAuth-Start-Key: YOUR_KEY` header. The server also includes this key as `key` in generated `authorization_url` values for unauthenticated MCP requests.
 
-After login, the callback page shows your **session token** with copy buttons.
+After login, the callback page shows three hosted auth options with copy buttons:
+
+| Hosted auth mode | How to select it | Best for |
+|------------------|------------------|----------|
+| **User/session mode** | Send `Authorization: Bearer <session-token>` and omit `X-Ebay-Server-Request` | Normal OAuth-aware MCP clients and user-scoped desktop clients. |
+| **Server request mode — identity headers** | Send `X-Ebay-Server-Request: true`, `X-Ebay-Client-Id`, `X-Ebay-User-Id`, and optional `X-Ebay-Environment` | Server/client setups that need to handle both regular user requests and backend server requests without copying a session token. |
+| **Server request mode — bearer-capable clients** | Send `X-Ebay-Server-Request: true` plus `Authorization: Bearer <mcp-server-issued-bearer-token>` | MCP clients or automation platforms that can store an authorization header but should not use the admin key. |
+
+Switching between modes is per request, not a server-wide environment toggle. The same hosted MCP server can handle user/session requests and server requests concurrently; the client chooses server mode by adding `X-Ebay-Server-Request: true`.
 
 **Session TTL schedule:**
 
@@ -351,8 +366,12 @@ POST/GET/DELETE /mcp   # resolves from ?env= or EBAY_ENVIRONMENT/EBAY_DEFAULT_EN
 - `GET /mcp` without token → redirects to `oauth/start`
 - `POST /mcp` without token → `401` JSON with `authorization_url`, `resource_metadata`, and a `WWW-Authenticate` Bearer challenge
 - Normal user requests: `Authorization: Bearer <session-token>`
+- Server requests with identity headers: `X-Ebay-Server-Request: true`, `X-Ebay-Client-Id: <client-id>`, `X-Ebay-User-Id: <user-id>`, `X-Ebay-Environment: sandbox|production`
+- Server requests with bearer-capable clients: `X-Ebay-Server-Request: true` plus `Authorization: Bearer <mcp-server-issued-bearer-token>`
 - Privileged admin bypass: `Authorization: Bearer <ADMIN_API_KEY>` when `ADMIN_API_KEY` is configured
 
+The `X-Ebay-Server-Request` header is intentionally client-side and per-request. Leave it off for normal user/session OAuth calls. Add it when the MCP client is making a server-style request and should resolve the stored Redis/KV user token record by headers or by the MCP server-issued bearer lookup token. This bearer lookup token is generated by this MCP server on the OAuth callback page; it is **not** an eBay user access token, eBay refresh token, eBay client-credentials/app token, legacy hosted session token, or `ADMIN_API_KEY`.
+
 #### Admin key bypass
 
 `ADMIN_API_KEY` is used in two distinct ways:
@@ -380,6 +399,31 @@ POST /admin/session/:sessionToken/revoke   # revoke session
 DELETE /admin/session/:sessionToken        # delete session
 ```
 
+### Admin endpoints
+
+All `/admin/*` routes accept authentication via either:
+- Header: `X-Admin-API-Key: <ADMIN_API_KEY>`
+- Query param: `?key=<ADMIN_API_KEY>` (useful for browser access)
+
+```
+GET  /admin/token-status              # OAuth + Playwright session health
+POST /admin/oauth/start-for-validation # Start OAuth flow for validation runner
+POST /admin/playwright-session        # Store Playwright storage state JSON
+GET  /admin/playwright-capture        # Browser UI to capture eBay Research cookies
+```
+
+**`/admin/playwright-capture`** renders a self-service page for renewing the eBay Research Playwright session. Open it in a browser with the admin key as a query parameter:
+
+```
+https://your-server.com/admin/playwright-capture?key=YOUR_ADMIN_API_KEY
+```
+
+The page has two tabs:
+1. **Auto-Capture** — loads eBay Research in an iframe (may be blocked by eBay's security policies)
+2. **Manual Export** — provides step-by-step instructions to export cookies from Chrome DevTools, a bookmarklet for one-click cookie copying, and a text area to paste and submit the JSON
+
+Submitted cookies are validated against the authenticated eBay Research ACTIVE endpoint before persistence, stored in the configured session backend (Upstash Redis / Cloudflare KV / filesystem), and written with a long KV TTL. Cookie expiry is tracked in metadata so the runtime can report missing/expired Terapeak auth separately from provider parsing failures.
+
 ### Validation endpoints
 
 ```
@@ -421,10 +465,48 @@ Cline auto-discovers OAuth, opens browser login, exchanges auth code, and stores
 }
 ```
 
+**Server request mode (custom headers):**
+1. Open `https://your-server.com/sandbox/oauth/start` or `https://your-server.com/production/oauth/start`
+2. Complete eBay login
+3. Copy the server request headers shown on the callback page
+4. Configure the MCP client with those headers:
+```json
+{
+  "mcpServers": {
+    "ebay-production-server": {
+      "url": "https://your-server.com/production/mcp",
+      "headers": {
+        "X-Ebay-Server-Request": "true",
+        "X-Ebay-Client-Id": "YOUR_EBAY_CLIENT_ID",
+        "X-Ebay-User-Id": "STORED_USER_ID_FROM_CALLBACK",
+        "X-Ebay-Environment": "production"
+      }
+    }
+  }
+}
+```
+
+**Server request mode (bearer-capable clients):**
+Use this when the MCP client can set `Authorization` but cannot easily send several custom identity headers:
+```json
+{
+  "mcpServers": {
+    "ebay-production-server": {
+      "url": "https://your-server.com/production/mcp",
+      "headers": {
+        "X-Ebay-Server-Request": "true",
+        "Authorization": "Bearer MCP_SERVER_ISSUED_BEARER_TOKEN_FROM_CALLBACK"
+      }
+    }
+  }
+}
+```
+
 **Make / Zapier / other platforms:**
 1. Complete OAuth via browser at `/oauth/start`
-2. Paste session token as API Key / Bearer token in connector settings
-3. Set MCP URL to `https://your-server.com/sandbox/mcp`
+2. If the platform supports multiple headers, use server request mode identity headers
+3. If the platform only supports one auth header, use server request mode with the MCP server-issued bearer lookup token from the callback page
+4. Set MCP URL to `https://your-server.com/sandbox/mcp`
 
 ---
 

package/build/auth/multi-user-store.js

@@ -1,4 +1,4 @@
-import { randomUUID } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import { createKVStore } from '../auth/kv-store.js';
 // ── TTL constants (seconds) ────────────────────────────────────────────────
 /** 15 minutes — matches the eBay OAuth state parameter lifetime. */
@@ -24,6 +24,22 @@ const DEFAULT_REFRESH_TOKEN_TTL_S = 18 * 30 * 24 * 60 * 60;
 function secondsFromNow(ttlSeconds) {
     return new Date(Date.now() + ttlSeconds * 1_000).toISOString();
 }
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function getTokenTtlSeconds(tokenData) {
+    let ttlSeconds = DEFAULT_REFRESH_TOKEN_TTL_S;
+    if (tokenData.userRefreshTokenExpiry) {
+        const expiryMs = typeof tokenData.userRefreshTokenExpiry === 'number'
+            ? tokenData.userRefreshTokenExpiry
+            : new Date(tokenData.userRefreshTokenExpiry).getTime();
+        const remaining = Math.floor((expiryMs - Date.now()) / 1_000);
+        if (remaining > 0) {
+            ttlSeconds = remaining;
+        }
+    }
+    return ttlSeconds;
+}
 export class MultiUserAuthStore {
     kv;
     /**
@@ -51,10 +67,16 @@ export class MultiUserAuthStore {
     userTokenKey(userId, environment) {
         return `user:${userId}:env:${environment}:tokens`;
     }
+    userTokenIndexKey(clientId, userId, environment) {
+        return `user_index:env:${environment}:client:${sha256(clientId)}:user:${userId}`;
+    }
+    serverBearerKey(token) {
+        return `server_bearer:${sha256(token)}`;
+    }
     sessionKey(sessionToken) {
         return `session:${sessionToken}`;
     }
-    async createOAuthState(environment, returnTo, mcpContext) {
+    async createOAuthState(environment, returnTo, mcpContext, targetUserId) {
         const state = randomUUID();
         const record = {
             state,
@@ -63,6 +85,7 @@ export class MultiUserAuthStore {
             expiresAt: secondsFromNow(OAUTH_STATE_TTL_S),
             returnTo,
             ...mcpContext,
+            ...(targetUserId ? { targetUserId } : {}),
         };
         await this.kv.put(this.stateKey(state), record, OAUTH_STATE_TTL_S);
         return record;
@@ -83,28 +106,70 @@ export class MultiUserAuthStore {
     }
     async saveUserTokens(userId, environment, tokenData) {
         // Derive TTL from refresh token expiry when available; fall back to 18 months.
-        let ttlSeconds = DEFAULT_REFRESH_TOKEN_TTL_S;
-        if (tokenData.userRefreshTokenExpiry) {
-            const expiryMs = typeof tokenData.userRefreshTokenExpiry === 'number'
-                ? tokenData.userRefreshTokenExpiry
-                : new Date(tokenData.userRefreshTokenExpiry).getTime();
-            const remaining = Math.floor((expiryMs - Date.now()) / 1_000);
-            if (remaining > 0) {
-                ttlSeconds = remaining;
-            }
-        }
+        const ttlSeconds = getTokenTtlSeconds(tokenData);
+        const now = new Date().toISOString();
         const record = {
             userId,
             environment,
             tokenData,
-            updatedAt: new Date().toISOString(),
+            updatedAt: now,
             expiresAt: secondsFromNow(ttlSeconds),
         };
         await this.kv.put(this.userTokenKey(userId, environment), record, ttlSeconds);
+        if (tokenData.clientId) {
+            const indexRecord = {
+                userId,
+                environment,
+                clientIdHash: sha256(tokenData.clientId),
+                createdAt: now,
+                updatedAt: now,
+                expiresAt: record.expiresAt,
+            };
+            await this.kv.put(this.userTokenIndexKey(tokenData.clientId, userId, environment), indexRecord, ttlSeconds);
+        }
     }
     async getUserTokens(userId, environment) {
         return await this.kv.get(this.userTokenKey(userId, environment));
     }
+    async getUserTokensByClientUser(clientId, userId, environment) {
+        const index = await this.kv.get(this.userTokenIndexKey(clientId, userId, environment));
+        if (index?.userId !== userId || index.environment !== environment) {
+            return null;
+        }
+        const record = await this.getUserTokens(index.userId, index.environment);
+        if (record?.tokenData.clientId !== clientId) {
+            return null;
+        }
+        return record;
+    }
+    async createServerBearerToken(userId, environment) {
+        const record = await this.getUserTokens(userId, environment);
+        if (!record?.tokenData) {
+            throw new Error(`Cannot create server bearer token without stored user tokens for ${userId}`);
+        }
+        const ttlSeconds = getTokenTtlSeconds(record.tokenData);
+        const token = `ebay_mcp_${randomUUID()}${randomUUID()}`;
+        const tokenHash = sha256(token);
+        const bearerRecord = {
+            tokenHash,
+            userId,
+            environment,
+            createdAt: new Date().toISOString(),
+            expiresAt: secondsFromNow(ttlSeconds),
+        };
+        await this.kv.put(this.serverBearerKey(token), bearerRecord, ttlSeconds);
+        return {
+            ...bearerRecord,
+            token,
+        };
+    }
+    async getUserTokensByServerBearerToken(token) {
+        const bearerRecord = await this.kv.get(this.serverBearerKey(token));
+        if (!bearerRecord) {
+            return null;
+        }
+        return await this.getUserTokens(bearerRecord.userId, bearerRecord.environment);
+    }
     async createSession(userId, environment) {
         const sessionToken = randomUUID() + randomUUID();
         const now = new Date().toISOString();

package/build/auth/oauth.js

@@ -16,6 +16,18 @@ export class EbayOAuthClient {
     getTokenEndpoint() {
         return `${getOAuthTokenBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
     }
+    getEffectiveClientCredentials() {
+        return {
+            clientId: this.userTokens?.clientId || this.config.clientId,
+            clientSecret: this.userTokens?.clientSecret || this.config.clientSecret,
+        };
+    }
+    getEffectiveRedirectUri() {
+        return (this.userTokens?.ruName ||
+            this.userTokens?.redirectUri ||
+            this.config.ruName ||
+            this.config.redirectUri);
+    }
     async initialize() {
         if (this.context?.userId && this.context.environment) {
             const stored = await this.authStore.getUserTokens(this.context.userId, this.context.environment);
@@ -115,7 +127,8 @@ export class EbayOAuthClient {
             return this.appAccessToken;
         }
         const authUrl = this.getTokenEndpoint();
-        const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+        const effectiveCredentials = this.getEffectiveClientCredentials();
+        const credentials = Buffer.from(`${effectiveCredentials.clientId}:${effectiveCredentials.clientSecret}`).toString('base64');
         const response = await axios.post(authUrl, new URLSearchParams({
             grant_type: 'client_credentials',
             scope: 'https://api.ebay.com/oauth/api_scope',
@@ -130,12 +143,13 @@ export class EbayOAuthClient {
         return this.appAccessToken;
     }
     async exchangeCodeForToken(code) {
-        const redirectUriForExchange = this.config.ruName || this.config.redirectUri;
+        const redirectUriForExchange = this.getEffectiveRedirectUri();
         if (!redirectUriForExchange) {
             throw new Error('RuName (EBAY_RUNAME) or redirectUri is required for authorization code exchange');
         }
         const tokenUrl = this.getTokenEndpoint();
-        const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+        const effectiveCredentials = this.getEffectiveClientCredentials();
+        const credentials = Buffer.from(`${effectiveCredentials.clientId}:${effectiveCredentials.clientSecret}`).toString('base64');
         try {
             const response = await axios.post(tokenUrl, new URLSearchParams({
                 grant_type: 'authorization_code',
@@ -150,10 +164,10 @@ export class EbayOAuthClient {
             const tokenData = response.data;
             const now = Date.now();
             this.userTokens = {
-                clientId: this.config.clientId,
-                clientSecret: this.config.clientSecret,
+                clientId: effectiveCredentials.clientId,
+                clientSecret: effectiveCredentials.clientSecret,
                 redirectUri: this.config.redirectUri,
-                ruName: this.config.ruName,
+                ruName: redirectUriForExchange,
                 userAccessToken: tokenData.access_token,
                 userRefreshToken: tokenData.refresh_token,
                 tokenType: tokenData.token_type,
@@ -183,7 +197,8 @@ export class EbayOAuthClient {
             throw new Error('No user tokens available to refresh');
         }
         const authUrl = this.getTokenEndpoint();
-        const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+        const effectiveCredentials = this.getEffectiveClientCredentials();
+        const credentials = Buffer.from(`${effectiveCredentials.clientId}:${effectiveCredentials.clientSecret}`).toString('base64');
         const response = await axios.post(authUrl, new URLSearchParams({
             grant_type: 'refresh_token',
             refresh_token: this.userTokens.userRefreshToken,
@@ -196,10 +211,10 @@ export class EbayOAuthClient {
         const tokenData = response.data;
         const now = Date.now();
         this.userTokens = {
-            clientId: this.config.clientId,
-            clientSecret: this.config.clientSecret,
-            redirectUri: this.config.redirectUri,
-            ruName: this.config.ruName,
+            clientId: effectiveCredentials.clientId,
+            clientSecret: effectiveCredentials.clientSecret,
+            redirectUri: this.userTokens.redirectUri || this.config.redirectUri,
+            ruName: this.userTokens.ruName || this.config.ruName,
             userAccessToken: tokenData.access_token,
             userRefreshToken: tokenData.refresh_token || this.userTokens.userRefreshToken,
             tokenType: tokenData.token_type,

package/build/captcha/captcha.js

@@ -0,0 +1,302 @@
+import { createLogger } from '../utils/logger.js';
+const logger = createLogger('captcha');
+function makeCaptchaError(provider, message, code) {
+    const error = new Error(message);
+    error.provider = provider;
+    error.code = code;
+    return error;
+}
+// ---------------------------------------------------------------------------
+// 2Captcha client
+// ---------------------------------------------------------------------------
+const TWOCAPTCHA_API_URL = 'https://2captcha.com';
+class TwoCaptchaClient {
+    name = 'twocaptcha';
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    captchaTypeToMethod(type) {
+        switch (type) {
+            case 'hcaptcha':
+                return 'hcaptcha';
+            case 'recaptcha_v2':
+                return 'usercaptcha';
+            case 'recaptcha_v3':
+                return 'userrecaptcha';
+        }
+    }
+    buildFormData(payload) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(payload)) {
+            if (value !== undefined) {
+                params.append(key, value);
+            }
+        }
+        return params;
+    }
+    async createTask(config) {
+        const method = this.captchaTypeToMethod(config.type);
+        const payload = {
+            key: this.apiKey,
+            method,
+            sitekey: config.siteKey,
+            pageurl: config.pageUrl,
+            proxy: config.proxy,
+            proxytype: config.proxy ? 'http' : undefined,
+            json: '1', // Force JSON response format
+        };
+        const formData = this.buildFormData(payload);
+        const response = await fetch(`${TWOCAPTCHA_API_URL}/in.php`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: formData,
+        });
+        // 2Captcha may return either JSON or plaintext OK|taskId format
+        const text = await response.text();
+        let data;
+        if (text.startsWith('{')) {
+            data = JSON.parse(text);
+        }
+        else {
+            // Parse plaintext OK|taskId or ERROR|message
+            const parts = text.split('|');
+            if (parts[0] === 'OK' && parts[1]) {
+                return { taskId: parts[1] };
+            }
+            data = { error_text: parts[1] ?? text, error_id: -1 };
+        }
+        if (data.status !== 1 || !data.request) {
+            const errorMessage = data.error_text ?? `2Captcha error_id: ${data.error_id}`;
+            throw makeCaptchaError(this.name, `2Captcha createTask failed: ${errorMessage}`, String(data.error_id));
+        }
+        return { taskId: data.request };
+    }
+    async getResult(taskId) {
+        const payload = {
+            key: this.apiKey,
+            action: 'get',
+            json: '1', // Force JSON response format
+            id: taskId,
+        };
+        const formData = this.buildFormData(payload);
+        const response = await fetch(`${TWOCAPTCHA_API_URL}/res.php`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: formData,
+        });
+        // Handle both JSON and plaintext formats
+        const text = await response.text();
+        let data;
+        if (text.startsWith('{')) {
+            data = JSON.parse(text);
+        }
+        else {
+            // Parse plaintext OK|solution or CAPCHA_NOT_READY
+            const parts = text.split('|');
+            if (parts[0] === 'OK' && parts[1]) {
+                return { token: parts[1], provider: this.name };
+            }
+            // CAPCHA_NOT_READY or other error
+            data = { error_text: parts[0] ?? text, error_id: 1 };
+        }
+        if (data.error_text && data.error_id !== 0) {
+            throw new Error(`2Captcha getResult error: ${data.error_text}`);
+        }
+        if (data.status === 1 && data.request) {
+            return { token: data.request, provider: this.name };
+        }
+        // Still processing (CAPCHA_NOT_READY)
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Solver factory
+// ---------------------------------------------------------------------------
+function resolveProvider() {
+    const twoCaptchaKey = process.env.TWOCAPTCHA_API_KEY;
+    if (twoCaptchaKey) {
+        logger.info('2Captcha client initialized');
+        return new TwoCaptchaClient(twoCaptchaKey);
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_MAX_POLL_MS = 60_000;
+export async function solveCaptcha(config, options = {}) {
+    const provider = resolveProvider();
+    if (!provider) {
+        throw new Error('No captcha solver configured. Set TWOCAPTCHA_API_KEY environment variable.');
+    }
+    const pollInterval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const maxWait = options.maxWaitMs ?? DEFAULT_MAX_POLL_MS;
+    logger.info(`Attempting captcha solve via ${provider.name} (type=${config.type})`);
+    try {
+        const { taskId } = await provider.createTask(config);
+        logger.debug(`Task created: ${taskId} on ${provider.name}`);
+        const deadline = Date.now() + maxWait;
+        while (Date.now() < deadline) {
+            await new Promise((resolve) => {
+                setTimeout(() => resolve(), pollInterval);
+            });
+            const solution = await provider.getResult(taskId);
+            if (solution) {
+                logger.info(`Captcha solved via ${provider.name}`);
+                return solution;
+            }
+        }
+        const timeoutError = makeCaptchaError(provider.name, `${provider.name} timed out after ${maxWait}ms`);
+        throw timeoutError;
+    }
+    catch (err) {
+        let providerError;
+        if (err instanceof Error && 'provider' in err) {
+            providerError = err;
+        }
+        else {
+            providerError = makeCaptchaError(provider.name, err instanceof Error ? err.message : String(err));
+        }
+        logger.warn(`${provider.name} failed: ${err instanceof Error ? err.message : String(err)}`);
+        throw providerError;
+    }
+}
+/**
+ * Inject the captcha solution token into a Playwright page.
+ */
+export async function injectCaptchaToken(page, type, token) {
+    if (type === 'hcaptcha') {
+        await page.evaluate((t) => {
+            const textarea = document.querySelector('textarea[name="h-captcha-response"]');
+            if (textarea) {
+                textarea.value = t;
+                textarea.dispatchEvent(new Event('input', { bubbles: true }));
+            }
+        }, token);
+    }
+    else {
+        await page.evaluate((t) => {
+            const iframe = document.querySelector('iframe[title="reCAPTCHA"], iframe[src*="recaptcha"]');
+            if (iframe) {
+                const iframeDoc = iframe.contentDocument;
+                if (iframeDoc) {
+                    const textarea = iframeDoc.querySelector('textarea[name="g-recaptcha-response"]');
+                    if (textarea) {
+                        textarea.value = t;
+                        textarea.dispatchEvent(new Event('input', { bubbles: true }));
+                    }
+                }
+            }
+        }, token);
+    }
+}
+/**
+ * Check if a captcha challenge is present on a Playwright page.
+ */
+export async function detectCaptcha(page) {
+    return await page.evaluate(() => {
+        const hcaptchaIframe = document.querySelector('iframe[src*="hcaptcha.com"]');
+        if (hcaptchaIframe)
+            return 'hcaptcha';
+        const hcaptchaWidget = document.querySelector('.hcaptcha');
+        if (hcaptchaWidget)
+            return 'hcaptcha';
+        const recaptchaIframe = document.querySelector('iframe[src*="recaptcha.net"], iframe[src*="recaptcha"]');
+        if (recaptchaIframe) {
+            const src = recaptchaIframe.src || '';
+            if (src.includes('render=explicit'))
+                return 'recaptcha_v3';
+            return 'recaptcha_v2';
+        }
+        const recaptchaWidget = document.querySelector('.g-recaptcha');
+        if (recaptchaWidget)
+            return 'recaptcha_v2';
+        return null;
+    });
+}
+/**
+ * Extract the captcha site key from the page.
+ */
+export async function extractSiteKey(page, type) {
+    return await page.evaluate((ct) => {
+        const captchaType = ct;
+        if (captchaType === 'hcaptcha') {
+            const hcaptchaEl = document.querySelector('.hcaptcha[data-sitekey]');
+            if (hcaptchaEl) {
+                return hcaptchaEl.getAttribute('data-sitekey');
+            }
+            const hcaptchaIframe = document.querySelector('iframe[src*="hcaptcha.com"]');
+            if (hcaptchaIframe) {
+                const src = hcaptchaIframe.src || '';
+                const match = /sitekey=([^&]+)/.exec(src);
+                if (match)
+                    return match[1];
+            }
+            const scripts = document.querySelectorAll('script');
+            for (const script of scripts) {
+                const text = script.textContent || '';
+                const match = /HCaptcha\.render\([^,]+,\s*['"]([^'"]+)['"]/.exec(text);
+                if (match)
+                    return match[1];
+            }
+            return null;
+        }
+        else {
+            const recaptchaEl = document.querySelector('.g-recaptcha[data-sitekey]');
+            if (recaptchaEl) {
+                return recaptchaEl.getAttribute('data-sitekey');
+            }
+            const recaptchaIframe = document.querySelector('iframe[src*="recaptcha"], iframe[src*="recaptcha.net"]');
+            if (recaptchaIframe) {
+                const src = recaptchaIframe.src || '';
+                const match = /k=([^&]+)/.exec(src);
+                if (match)
+                    return match[1];
+            }
+            const scripts = document.querySelectorAll('script');
+            for (const script of scripts) {
+                const text = script.textContent || '';
+                const match = /grecaptcha\.render\([^,]+,\s*['"]([^'"]+)['"]/.exec(text);
+                if (match)
+                    return match[1];
+            }
+            return null;
+        }
+    }, type);
+}
+/**
+ * Helper: wait for captcha to appear on page, then solve and inject.
+ */
+export async function waitForAndSolveCaptcha(page, options) {
+    const maxWait = options.maxWaitMs ?? 30_000;
+    const checkInterval = options.checkIntervalMs ?? 1_000;
+    const deadline = Date.now() + maxWait;
+    while (Date.now() < deadline) {
+        const captchaType = await detectCaptcha(page);
+        if (captchaType) {
+            logger.info(`Detected ${captchaType} on ${options.pageUrl}`);
+            const siteKey = await extractSiteKey(page, captchaType);
+            if (!siteKey) {
+                logger.error('Captcha detected but site key could not be extracted');
+                throw new Error('Could not extract captcha site key from page');
+            }
+            logger.debug(`Extracted site key: ${siteKey}`);
+            const solution = await solveCaptcha({
+                type: captchaType,
+                siteKey,
+                pageUrl: options.pageUrl,
+                proxy: options.proxy,
+            });
+            await injectCaptchaToken(page, captchaType, solution.token);
+            logger.info(`Injected ${captchaType} solution token`);
+            return solution;
+        }
+        await new Promise((resolve) => {
+            setTimeout(() => resolve(), checkInterval);
+        });
+    }
+    logger.debug('No captcha detected within timeout');
+    return null;
+}

package/build/config/environment.js

@@ -166,7 +166,7 @@ export function ruNameToEnvironment(ruName) {
  */
 export function validateCredentialsForEnvironment(environment) {
     const config = getEbayConfig(environment);
-    const ruName = config.redirectUri;
+    const ruName = config.ruName || config.redirectUri;
     const detectedEnv = ruNameToEnvironment(ruName);
     if (detectedEnv === null) {
         // Can't tell from the RuName — treat as valid (no info to contradict it).