@browserstack/mcp-server 1.2.15-beta.1 → 1.2.15-beta.3

package/dist/lib/percy-api/auth.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Percy API authentication module.
+ * Resolves Percy tokens via environment variables or BrowserStack credential fallback.
+ *
+ * SECURITY: Token values are NEVER logged or included in error messages.
+ * Masked format (****<last4>) is used when referencing tokens in diagnostics.
+ */
+import { BrowserStackConfig } from "../types.js";
+type TokenScope = "project" | "org" | "auto";
+interface ResolveTokenOptions {
+    projectName?: string;
+    scope?: TokenScope;
+}
+/**
+ * Masks a token for safe display in error messages.
+ * Shows only the last 4 characters.
+ */
+export declare function maskToken(token: string): string;
+/**
+ * Resolves a Percy token using the following priority:
+ *
+ * 1. `process.env.PERCY_TOKEN` (for project or auto scope)
+ * 2. `process.env.PERCY_ORG_TOKEN` (for org scope)
+ * 3. Fallback: fetch via BrowserStack API using `fetchPercyToken()`
+ * 4. If nothing works, throws an enriched error with guidance
+ */
+export declare function resolvePercyToken(config: BrowserStackConfig, options?: ResolveTokenOptions): Promise<string>;
+/**
+ * Returns headers for Percy API requests.
+ * Includes Authorization, Content-Type, and User-Agent.
+ */
+export declare function getPercyHeaders(config: BrowserStackConfig, options?: {
+    scope?: TokenScope;
+    projectName?: string;
+}): Promise<Record<string, string>>;
+/**
+ * Returns the Percy API base URL.
+ * Defaults to `https://percy.io/api/v1`, overridable via `PERCY_API_URL` env var.
+ */
+export declare function getPercyApiBaseUrl(): string;
+export {};

package/dist/lib/percy-api/auth.js

@@ -0,0 +1,96 @@
+/**
+ * Percy API authentication module.
+ * Resolves Percy tokens via environment variables or BrowserStack credential fallback.
+ *
+ * SECURITY: Token values are NEVER logged or included in error messages.
+ * Masked format (****<last4>) is used when referencing tokens in diagnostics.
+ */
+import { fetchPercyToken } from "../../tools/sdk-utils/percy-web/fetchPercyToken.js";
+/**
+ * Masks a token for safe display in error messages.
+ * Shows only the last 4 characters.
+ */
+export function maskToken(token) {
+    if (token.length <= 4) {
+        return "****";
+    }
+    return `****${token.slice(-4)}`;
+}
+/**
+ * Resolves a Percy token using the following priority:
+ *
+ * 1. `process.env.PERCY_TOKEN` (for project or auto scope)
+ * 2. `process.env.PERCY_ORG_TOKEN` (for org scope)
+ * 3. Fallback: fetch via BrowserStack API using `fetchPercyToken()`
+ * 4. If nothing works, throws an enriched error with guidance
+ */
+export async function resolvePercyToken(config, options = {}) {
+    const { projectName, scope = "auto" } = options;
+    // For project or auto scope, check PERCY_TOKEN first
+    if (scope === "project" || scope === "auto") {
+        const envToken = process.env.PERCY_TOKEN;
+        if (envToken) {
+            return envToken;
+        }
+    }
+    // For org scope, check PERCY_ORG_TOKEN
+    if (scope === "org") {
+        const orgToken = process.env.PERCY_ORG_TOKEN;
+        if (orgToken) {
+            return orgToken;
+        }
+    }
+    // For auto scope, also check PERCY_ORG_TOKEN as secondary
+    if (scope === "auto") {
+        const orgToken = process.env.PERCY_ORG_TOKEN;
+        if (orgToken) {
+            return orgToken;
+        }
+    }
+    // Fallback: fetch via BrowserStack credentials
+    const username = config["browserstack-username"];
+    const accessKey = config["browserstack-access-key"];
+    if (username && accessKey) {
+        const auth = `${username}:${accessKey}`;
+        const resolvedProjectName = projectName || "default";
+        try {
+            const token = await fetchPercyToken(resolvedProjectName, auth, {});
+            return token;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to fetch Percy token via BrowserStack API: ${message}. ` +
+                `Set PERCY_TOKEN or PERCY_ORG_TOKEN environment variable as an alternative.`);
+        }
+    }
+    // Nothing worked — provide actionable guidance
+    if (scope === "project") {
+        throw new Error("Percy project token not available. Set PERCY_TOKEN environment variable, " +
+            "or provide BrowserStack credentials to fetch a token automatically.");
+    }
+    if (scope === "org") {
+        throw new Error("Percy org token not available. Set PERCY_ORG_TOKEN environment variable.");
+    }
+    throw new Error("Percy token not available. Set PERCY_TOKEN (project) or PERCY_ORG_TOKEN (org) " +
+        "environment variable, or provide BrowserStack credentials (browserstack-username " +
+        "and browserstack-access-key) to fetch a token automatically.");
+}
+/**
+ * Returns headers for Percy API requests.
+ * Includes Authorization, Content-Type, and User-Agent.
+ */
+export async function getPercyHeaders(config, options = {}) {
+    const token = await resolvePercyToken(config, options);
+    return {
+        Authorization: `Token token=${token}`,
+        "Content-Type": "application/json",
+        "User-Agent": "browserstack-mcp-server",
+    };
+}
+/**
+ * Returns the Percy API base URL.
+ * Defaults to `https://percy.io/api/v1`, overridable via `PERCY_API_URL` env var.
+ */
+export function getPercyApiBaseUrl() {
+    return process.env.PERCY_API_URL || "https://percy.io/api/v1";
+}

package/dist/lib/percy-api/build-items.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared helpers for the /build-items endpoint.
+ *
+ * Pagination: the API returns everything when page[limit] is omitted, but may
+ * still paginate (meta.pagination.has_more + next_cursor) on very large
+ * builds or if server-side defaults change. fetchAllBuildItems handles both:
+ * it starts with an unbounded request and follows next_cursor if the response
+ * is paginated anyway.
+ */
+import { BrowserStackConfig } from "../types.js";
+export interface BuildItemsResult {
+    items: any[];
+    /** True if pagination could not be exhausted (page cap or cursor stall). */
+    truncated: boolean;
+}
+/**
+ * Fetch ALL build items for the given filters, following
+ * meta.pagination.next_cursor until has_more is false.
+ */
+export declare function fetchAllBuildItems(config: BrowserStackConfig, baseParams: Record<string, string | string[]>): Promise<BuildItemsResult>;
+/**
+ * Filter params that make filter[category]=changed actually return results.
+ * The API only maps the changed category to review states via
+ * filter[subcategories][]; without it the scope resolves to zero rows.
+ */
+export declare const CHANGED_CATEGORY_PARAMS: Record<string, string | string[]>;
+/**
+ * Format a 0..1 diff ratio as a percentage without hiding small diffs:
+ * 0 → "0%", tiny → "<0.01%", otherwise two decimals (e.g. "0.02%").
+ */
+export declare function formatDiffPercent(ratio: number | null | undefined): string;

package/dist/lib/percy-api/build-items.js

@@ -0,0 +1,61 @@
+/**
+ * Shared helpers for the /build-items endpoint.
+ *
+ * Pagination: the API returns everything when page[limit] is omitted, but may
+ * still paginate (meta.pagination.has_more + next_cursor) on very large
+ * builds or if server-side defaults change. fetchAllBuildItems handles both:
+ * it starts with an unbounded request and follows next_cursor if the response
+ * is paginated anyway.
+ */
+import { percyGet } from "./percy-auth.js";
+const MAX_PAGES = 50;
+/**
+ * Fetch ALL build items for the given filters, following
+ * meta.pagination.next_cursor until has_more is false.
+ */
+export async function fetchAllBuildItems(config, baseParams) {
+    const items = [];
+    let cursor;
+    let pages = 0;
+    for (;;) {
+        const params = { ...baseParams };
+        if (cursor)
+            params["page[cursor]"] = cursor;
+        const response = await percyGet("/build-items", config, params);
+        items.push(...(response?.data || []));
+        pages += 1;
+        const pagination = response?.meta?.pagination;
+        const nextCursor = pagination?.next_cursor;
+        if (!pagination?.has_more || !nextCursor) {
+            return { items, truncated: false };
+        }
+        // Guard against a stalled cursor or runaway loop.
+        if (nextCursor === cursor || pages >= MAX_PAGES) {
+            return { items, truncated: true };
+        }
+        cursor = String(nextCursor);
+    }
+}
+/**
+ * Filter params that make filter[category]=changed actually return results.
+ * The API only maps the changed category to review states via
+ * filter[subcategories][]; without it the scope resolves to zero rows.
+ */
+export const CHANGED_CATEGORY_PARAMS = {
+    "filter[category]": "changed",
+    "filter[subcategories][]": ["unreviewed", "changes_requested", "approved"],
+};
+/**
+ * Format a 0..1 diff ratio as a percentage without hiding small diffs:
+ * 0 → "0%", tiny → "<0.01%", otherwise two decimals (e.g. "0.02%").
+ */
+export function formatDiffPercent(ratio) {
+    if (ratio == null)
+        return "—";
+    const pct = ratio * 100;
+    if (pct === 0)
+        return "0%";
+    if (pct < 0.01)
+        return "<0.01%";
+    return pct.toFixed(2) + "%";
+}

package/dist/lib/percy-api/cache.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Simple in-memory cache with per-entry TTL.
+ *
+ * Used to cache Percy API responses and avoid redundant network calls
+ * within short time windows (e.g., multiple tools querying the same build).
+ */
+export declare class PercyCache {
+    private store;
+    /**
+     * Returns the cached value if it exists and has not expired.
+     * Expired entries are deleted on access.
+     */
+    get<T>(key: string): T | null;
+    /**
+     * Stores a value with an optional TTL (defaults to 30 seconds).
+     */
+    set(key: string, value: unknown, ttlMs?: number): void;
+    /**
+     * Removes all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Removes a single entry from the cache.
+     */
+    delete(key: string): void;
+}
+/** Singleton cache instance shared across Percy API tools. */
+export declare const percyCache: PercyCache;

package/dist/lib/percy-api/cache.js

@@ -0,0 +1,48 @@
+/**
+ * Simple in-memory cache with per-entry TTL.
+ *
+ * Used to cache Percy API responses and avoid redundant network calls
+ * within short time windows (e.g., multiple tools querying the same build).
+ */
+const DEFAULT_TTL_MS = 30_000; // 30 seconds
+export class PercyCache {
+    store = new Map();
+    /**
+     * Returns the cached value if it exists and has not expired.
+     * Expired entries are deleted on access.
+     */
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry) {
+            return null;
+        }
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    /**
+     * Stores a value with an optional TTL (defaults to 30 seconds).
+     */
+    set(key, value, ttlMs = DEFAULT_TTL_MS) {
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+    /**
+     * Removes all entries from the cache.
+     */
+    clear() {
+        this.store.clear();
+    }
+    /**
+     * Removes a single entry from the cache.
+     */
+    delete(key) {
+        this.store.delete(key);
+    }
+}
+/** Singleton cache instance shared across Percy API tools. */
+export const percyCache = new PercyCache();

package/dist/lib/percy-api/client.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Percy API HTTP client.
+ *
+ * Uses native `fetch` (consistent with existing Percy tools in this repo).
+ * Handles JSON:API deserialization, rate limiting, and error enrichment.
+ *
+ * SECURITY: Token values are NEVER logged or exposed in error messages.
+ */
+import { BrowserStackConfig } from "../types.js";
+type TokenScope = "project" | "org" | "auto";
+interface ClientOptions {
+    scope?: TokenScope;
+    projectName?: string;
+}
+interface JsonApiResource {
+    id: string;
+    type: string;
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, {
+        data: {
+            id: string;
+            type: string;
+        } | Array<{
+            id: string;
+            type: string;
+        }> | null;
+    }>;
+}
+interface JsonApiEnvelope {
+    data: JsonApiResource | JsonApiResource[] | null;
+    included?: JsonApiResource[];
+    meta?: Record<string, unknown>;
+}
+/**
+ * Deserializes a JSON:API envelope into plain objects.
+ *
+ * - `data: null` → returns `null`
+ * - `data: []` → returns `[]`
+ * - `data: { ... }` → returns a single deserialized object
+ * - `data: [{ ... }, ...]` → returns an array of deserialized objects
+ */
+export declare function deserialize(envelope: JsonApiEnvelope): {
+    data: Record<string, unknown> | Record<string, unknown>[] | null;
+    meta?: Record<string, unknown>;
+};
+export declare class PercyClient {
+    private config;
+    private options;
+    constructor(config: BrowserStackConfig, options?: ClientOptions);
+    /**
+     * GET request with optional query params and JSON:API `include`.
+     */
+    get<T = Record<string, unknown>>(path: string, params?: Record<string, string>, includes?: string[]): Promise<T>;
+    /**
+     * POST request with an optional JSON body.
+     */
+    post<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
+    /**
+     * PATCH request with an optional JSON body.
+     */
+    patch<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
+    /**
+     * DELETE request.
+     */
+    del(path: string): Promise<void>;
+    private buildUrl;
+    private request;
+}
+export {};

package/dist/lib/percy-api/client.js

@@ -0,0 +1,275 @@
+/**
+ * Percy API HTTP client.
+ *
+ * Uses native `fetch` (consistent with existing Percy tools in this repo).
+ * Handles JSON:API deserialization, rate limiting, and error enrichment.
+ *
+ * SECURITY: Token values are NEVER logged or exposed in error messages.
+ */
+import { getPercyHeaders, getPercyApiBaseUrl } from "./auth.js";
+import { enrichPercyError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Helpers – kebab-case to camelCase
+// ---------------------------------------------------------------------------
+function kebabToCamel(str) {
+    return str.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
+}
+function camelCaseKeys(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(camelCaseKeys);
+    }
+    if (typeof obj === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const camelKey = kebabToCamel(key);
+            result[camelKey] =
+                value !== null && typeof value === "object"
+                    ? camelCaseKeys(value)
+                    : value;
+        }
+        return result;
+    }
+    return obj;
+}
+// ---------------------------------------------------------------------------
+// JSON:API Deserializer
+// ---------------------------------------------------------------------------
+/**
+ * Builds a lookup index of included resources keyed by `type:id`.
+ */
+function buildIncludedIndex(included) {
+    const index = new Map();
+    for (const resource of included) {
+        const flattened = flattenResource(resource);
+        index.set(`${resource.type}:${resource.id}`, flattened);
+    }
+    return index;
+}
+/**
+ * Flattens a single JSON:API resource — merges `attributes` into the top
+ * level alongside `id` and `type`, converting keys to camelCase.
+ */
+function flattenResource(resource) {
+    const attrs = resource.attributes
+        ? camelCaseKeys(resource.attributes)
+        : {};
+    return {
+        id: resource.id,
+        type: resource.type,
+        ...attrs,
+    };
+}
+/**
+ * Resolves relationships for a resource against the included index.
+ * Returns the resolved object(s) or the raw { id, type } ref when not found.
+ */
+function resolveRelationships(resource, index) {
+    if (!resource.relationships) {
+        return {};
+    }
+    const resolved = {};
+    for (const [relName, relValue] of Object.entries(resource.relationships)) {
+        const camelName = kebabToCamel(relName);
+        const { data } = relValue;
+        if (data === null || data === undefined) {
+            resolved[camelName] = null;
+        }
+        else if (Array.isArray(data)) {
+            resolved[camelName] = data.map((ref) => index.get(`${ref.type}:${ref.id}`) ?? { id: ref.id, type: ref.type });
+        }
+        else {
+            resolved[camelName] = index.get(`${data.type}:${data.id}`) ?? {
+                id: data.id,
+                type: data.type,
+            };
+        }
+    }
+    return resolved;
+}
+/**
+ * Deserializes a JSON:API envelope into plain objects.
+ *
+ * - `data: null` → returns `null`
+ * - `data: []` → returns `[]`
+ * - `data: { ... }` → returns a single deserialized object
+ * - `data: [{ ... }, ...]` → returns an array of deserialized objects
+ */
+export function deserialize(envelope) {
+    const included = envelope.included ?? [];
+    const index = buildIncludedIndex(included);
+    if (envelope.data === null || envelope.data === undefined) {
+        return { data: null, meta: envelope.meta };
+    }
+    if (Array.isArray(envelope.data)) {
+        const records = envelope.data.map((resource) => ({
+            ...flattenResource(resource),
+            ...resolveRelationships(resource, index),
+        }));
+        return { data: records, meta: envelope.meta };
+    }
+    const record = {
+        ...flattenResource(envelope.data),
+        ...resolveRelationships(envelope.data, index),
+    };
+    return { data: record, meta: envelope.meta };
+}
+// ---------------------------------------------------------------------------
+// Rate Limit / Retry
+// ---------------------------------------------------------------------------
+const MAX_RETRIES = 3;
+const BASE_RETRY_DELAY_MS = 1_000;
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
+// PercyClient
+// ---------------------------------------------------------------------------
+export class PercyClient {
+    config;
+    options;
+    constructor(config, options) {
+        this.config = config;
+        this.options = options ?? {};
+    }
+    // -----------------------------------------------------------------------
+    // Public HTTP methods
+    // -----------------------------------------------------------------------
+    /**
+     * GET request with optional query params and JSON:API `include`.
+     */
+    async get(path, params, includes) {
+        const url = this.buildUrl(path, params, includes);
+        return this.request("GET", url);
+    }
+    /**
+     * POST request with an optional JSON body.
+     */
+    async post(path, body) {
+        const url = this.buildUrl(path);
+        return this.request("POST", url, body);
+    }
+    /**
+     * PATCH request with an optional JSON body.
+     */
+    async patch(path, body) {
+        const url = this.buildUrl(path);
+        return this.request("PATCH", url, body);
+    }
+    /**
+     * DELETE request.
+     */
+    async del(path) {
+        const url = this.buildUrl(path);
+        await this.request("DELETE", url);
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    buildUrl(path, params, includes) {
+        const base = getPercyApiBaseUrl();
+        // Ensure no double slashes between base and path
+        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        const url = new URL(`${base}${normalizedPath}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        if (includes && includes.length > 0) {
+            url.searchParams.set("include", includes.join(","));
+        }
+        return url.toString();
+    }
+    async request(method, url, body) {
+        const headers = await getPercyHeaders(this.config, {
+            scope: this.options.scope,
+            projectName: this.options.projectName,
+        });
+        let lastError;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            const fetchOptions = {
+                method,
+                headers,
+            };
+            if (body !== undefined) {
+                fetchOptions.body = JSON.stringify(body);
+            }
+            let response;
+            try {
+                response = await fetch(url, fetchOptions);
+            }
+            catch (networkError) {
+                lastError =
+                    networkError instanceof Error
+                        ? networkError
+                        : new Error(String(networkError));
+                // Network errors are not retryable via the rate-limit path,
+                // but we still respect the retry loop for consistency.
+                if (attempt < MAX_RETRIES) {
+                    await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                    continue;
+                }
+                throw lastError;
+            }
+            // 204 No Content
+            if (response.status === 204) {
+                return undefined;
+            }
+            // Rate limited — retry with backoff
+            if (response.status === 429) {
+                const retryAfter = response.headers.get("Retry-After");
+                const delayMs = retryAfter
+                    ? parseFloat(retryAfter) * 1_000
+                    : BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+                if (attempt < MAX_RETRIES) {
+                    await sleep(delayMs);
+                    continue;
+                }
+                // Exhausted retries — throw enriched error
+                let errorBody;
+                try {
+                    errorBody = await response.json();
+                }
+                catch {
+                    errorBody = undefined;
+                }
+                throw enrichPercyError(429, errorBody, `${method} ${url}`);
+            }
+            // Non-2xx error
+            if (!response.ok) {
+                let errorBody;
+                try {
+                    errorBody = await response.json();
+                }
+                catch {
+                    errorBody = undefined;
+                }
+                throw enrichPercyError(response.status, errorBody, `${method} ${url}`);
+            }
+            // Successful JSON response — deserialize JSON:API
+            const json = await response.json();
+            // If the response has a JSON:API `data` key, deserialize it
+            if (json && typeof json === "object" && "data" in json) {
+                const deserialized = deserialize(json);
+                // Unwrap: return the data directly (single object or array)
+                // Attach meta as a non-enumerable property so it's accessible but doesn't clutter
+                const result = deserialized.data;
+                if (result && typeof result === "object" && deserialized.meta) {
+                    Object.defineProperty(result, "__meta", {
+                        value: deserialized.meta,
+                        enumerable: false,
+                        writable: false,
+                    });
+                }
+                return result;
+            }
+            // Non-JSON:API response — return as-is
+            return json;
+        }
+        // Should not reach here, but satisfy TypeScript
+        throw lastError ?? new Error("Request failed after retries");
+    }
+}

package/dist/lib/percy-api/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Percy API error enrichment module.
+ * Maps Percy API error responses to actionable, user-friendly messages.
+ */
+export declare class PercyApiError extends Error {
+    statusCode: number;
+    errorCode?: string;
+    body?: unknown;
+    constructor(message: string, statusCode: number, errorCode?: string, body?: unknown);
+}
+/**
+ * Maps Percy API error responses to actionable messages.
+ * Handles known error codes from Percy's JSON:API responses.
+ */
+export declare function enrichPercyError(status: number, body: unknown, context?: string): PercyApiError;