@showrun/core 0.1.8 → 0.1.10-rc.0

package/dist/__tests__/dsl-validation.test.js

@@ -201,3 +201,188 @@ describe('validateFlow — unknown params rejection', () => {
         expect(errors[0]).toContain('Unknown step type: custom_magic');
     });
 });
+describe('validateFlow — dom_scrape step', () => {
+    const validDomScrape = {
+        id: 'scrape_results',
+        type: 'dom_scrape',
+        params: {
+            target: { kind: 'css', selector: '.search-result' },
+            collect: [
+                { key: 'title', target: { kind: 'css', selector: 'h3' } },
+                { key: 'url', target: { kind: 'css', selector: 'a' }, extract: 'attribute', attribute: 'href' },
+                { key: 'description', target: { kind: 'css', selector: '.snippet' } },
+            ],
+            skip_empty: true,
+            out: 'results',
+        },
+    };
+    it('accepts a valid dom_scrape step', () => {
+        const errors = [];
+        validateFlow([validDomScrape], errors);
+        expect(errors).toEqual([]);
+    });
+    it('accepts dom_scrape with legacy selector', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_legacy',
+                type: 'dom_scrape',
+                params: {
+                    selector: '.item',
+                    collect: [{ key: 'name', target: { kind: 'css', selector: 'span' } }],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors).toEqual([]);
+    });
+    it('errors when missing target and selector', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_no_target',
+                type: 'dom_scrape',
+                params: {
+                    collect: [{ key: 'name', target: { kind: 'css', selector: 'span' } }],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('must have either "selector" or "target"'))).toBe(true);
+    });
+    it('errors when missing out', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_no_out',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [{ key: 'name', target: { kind: 'css', selector: 'span' } }],
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('non-empty string "out"'))).toBe(true);
+    });
+    it('errors when collect is empty', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_empty_collect',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('non-empty "collect" array'))).toBe(true);
+    });
+    it('errors when collect is missing', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_missing_collect',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('non-empty "collect" array'))).toBe(true);
+    });
+    it('errors on duplicate collect keys', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_dup_keys',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [
+                        { key: 'name', target: { kind: 'css', selector: 'h3' } },
+                        { key: 'name', target: { kind: 'css', selector: 'h4' } },
+                    ],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('duplicate key "name"'))).toBe(true);
+    });
+    it('errors when collect field missing key', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_no_key',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [{ target: { kind: 'css', selector: 'span' } }],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('collect[0] must have a non-empty string "key"'))).toBe(true);
+    });
+    it('errors when collect field missing target', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_no_field_target',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [{ key: 'name' }],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('collect[0] must have a "target"'))).toBe(true);
+    });
+    it('errors when extract is "attribute" but attribute is missing', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_attr_missing',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [
+                        { key: 'url', target: { kind: 'css', selector: 'a' }, extract: 'attribute' },
+                    ],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('requires "attribute" when extract is "attribute"'))).toBe(true);
+    });
+    it('errors on invalid extract value', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_bad_extract',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [
+                        { key: 'val', target: { kind: 'css', selector: 'span' }, extract: 'innerText' },
+                    ],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('"extract" must be "text", "attribute", or "html"'))).toBe(true);
+    });
+    it('errors on unknown fields in collect entry', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_unknown_field',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [
+                        { key: 'name', target: { kind: 'css', selector: 'span' }, trim: true },
+                    ],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors.some(e => e.includes('unknown field(s): "trim"'))).toBe(true);
+    });
+    it('accepts dom_scrape with html extract', () => {
+        const errors = [];
+        validateFlow([{
+                id: 'scrape_html',
+                type: 'dom_scrape',
+                params: {
+                    target: { kind: 'css', selector: '.item' },
+                    collect: [
+                        { key: 'content', target: { kind: 'css', selector: '.body' }, extract: 'html' },
+                    ],
+                    out: 'items',
+                },
+            }], errors);
+        expect(errors).toEqual([]);
+    });
+});

package/dist/__tests__/httpReplay.test.js

@@ -97,6 +97,68 @@ describe('isFlowHttpCompatible', () => {
         ];
         expect(isFlowHttpCompatible(steps, snapshots)).toBe(false);
     });
+    it('returns false when a navigate step has a dynamic template URL', () => {
+        const steps = [
+            { id: 'nav1', type: 'navigate', params: { url: 'https://example.com/items?batch={{inputs.batch | urlencode}}' } },
+            { id: 'find1', type: 'network_find', params: { where: { urlIncludes: '/api/' }, saveAs: 'reqId' } },
+            {
+                id: 'replay1', type: 'network_replay',
+                params: { requestId: '{{vars.reqId}}', auth: 'browser_context', out: 'data', response: { as: 'json' } },
+            },
+        ];
+        const snapshots = makeSnapshotFile(['replay1']);
+        expect(isFlowHttpCompatible(steps, snapshots)).toBe(false);
+    });
+    it('returns false when a fill step has a dynamic template value', () => {
+        const steps = [
+            { id: 'nav1', type: 'navigate', params: { url: 'https://example.com' } },
+            { id: 'fill1', type: 'fill', params: { target: { kind: 'css', selector: '#search' }, value: '{{inputs.query}}' } },
+            {
+                id: 'replay1', type: 'network_replay',
+                params: { requestId: '{{vars.reqId}}', auth: 'browser_context', out: 'data', response: { as: 'json' } },
+            },
+        ];
+        const snapshots = makeSnapshotFile(['replay1']);
+        expect(isFlowHttpCompatible(steps, snapshots)).toBe(false);
+    });
+    it('returns false when a click step has a dynamic template target', () => {
+        const steps = [
+            { id: 'nav1', type: 'navigate', params: { url: 'https://example.com' } },
+            { id: 'click1', type: 'click', params: { target: { kind: 'text', text: '{{inputs.category}}' } } },
+            {
+                id: 'replay1', type: 'network_replay',
+                params: { requestId: '{{vars.reqId}}', auth: 'browser_context', out: 'data', response: { as: 'json' } },
+            },
+        ];
+        const snapshots = makeSnapshotFile(['replay1']);
+        expect(isFlowHttpCompatible(steps, snapshots)).toBe(false);
+    });
+    it('allows static navigate step (no templates) in HTTP mode', () => {
+        const steps = [
+            { id: 'nav1', type: 'navigate', params: { url: 'https://example.com/page' } },
+            {
+                id: 'replay1', type: 'network_replay',
+                params: { requestId: '{{vars.reqId}}', auth: 'browser_context', out: 'data', response: { as: 'json' } },
+            },
+        ];
+        const snapshots = makeSnapshotFile(['replay1']);
+        expect(isFlowHttpCompatible(steps, snapshots)).toBe(true);
+    });
+    it('templates in network_replay params do NOT block HTTP mode (they are resolved at replay time)', () => {
+        const steps = [
+            { id: 'nav1', type: 'navigate', params: { url: 'https://example.com' } },
+            {
+                id: 'replay1', type: 'network_replay',
+                params: {
+                    requestId: '{{vars.reqId}}', auth: 'browser_context', out: 'data',
+                    response: { as: 'json' },
+                    overrides: { bodyReplace: [{ find: 'W24', replace: '{{inputs.batch}}' }] },
+                },
+            },
+        ];
+        const snapshots = makeSnapshotFile(['replay1']);
+        expect(isFlowHttpCompatible(steps, snapshots)).toBe(true);
+    });
     it('allows sleep, set_var, and network_extract in HTTP mode', () => {
         const steps = [
             {

package/dist/__tests__/proxy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=proxy.test.d.ts.map

package/dist/__tests__/proxy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/proxy.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/proxy.test.js

@@ -0,0 +1,117 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { OxylabsProvider } from '../proxy/oxylabs.js';
+import { resolveProxy, registerProxyProvider, getProxyProvider, listProxyProviders, } from '../proxy/proxyService.js';
+describe('OxylabsProvider', () => {
+    const provider = new OxylabsProvider();
+    const creds = { username: 'testuser', password: 'testpass' };
+    it('generates correct random mode username', () => {
+        const config = { enabled: true, mode: 'random' };
+        const result = provider.resolve(config, creds);
+        expect(result.server).toBe('http://pr.oxylabs.io:7777');
+        expect(result.username).toBe('customer-testuser');
+        expect(result.password).toBe('testpass');
+    });
+    it('generates correct session mode username with sessid and sesstime', () => {
+        const config = { enabled: true, mode: 'session', sessionDurationMinutes: 15 };
+        const result = provider.resolve(config, creds);
+        expect(result.server).toBe('http://pr.oxylabs.io:7777');
+        expect(result.username).toMatch(/^customer-testuser-sessid-[a-f0-9]+-sesstime-15$/);
+        expect(result.password).toBe('testpass');
+    });
+    it('defaults to session mode when mode is not specified', () => {
+        const config = { enabled: true };
+        const result = provider.resolve(config, creds);
+        expect(result.username).toContain('-sessid-');
+        expect(result.username).toContain('-sesstime-10'); // default 10 min
+    });
+    it('includes country code when specified', () => {
+        const config = { enabled: true, mode: 'random', country: 'US' };
+        const result = provider.resolve(config, creds);
+        expect(result.username).toBe('customer-testuser-cc-US');
+    });
+    it('uppercases country code', () => {
+        const config = { enabled: true, mode: 'random', country: 'gb' };
+        const result = provider.resolve(config, creds);
+        expect(result.username).toBe('customer-testuser-cc-GB');
+    });
+    it('includes country before session params in session mode', () => {
+        const config = { enabled: true, mode: 'session', country: 'DE' };
+        const result = provider.resolve(config, creds);
+        expect(result.username).toMatch(/^customer-testuser-cc-DE-sessid-[a-f0-9]+-sesstime-10$/);
+    });
+    it('reports required credential keys', () => {
+        expect(provider.requiredCredentialKeys()).toEqual(['USERNAME', 'PASSWORD']);
+    });
+});
+describe('resolveProxy', () => {
+    const originalEnv = { ...process.env };
+    beforeEach(() => {
+        // Clean proxy env vars before each test
+        delete process.env.SHOWRUN_PROXY_USERNAME;
+        delete process.env.SHOWRUN_PROXY_PASSWORD;
+        delete process.env.SHOWRUN_PROXY_PROVIDER;
+    });
+    afterEach(() => {
+        // Restore original env
+        process.env = { ...originalEnv };
+    });
+    it('returns null for undefined config', () => {
+        expect(resolveProxy(undefined)).toBeNull();
+    });
+    it('returns null for disabled config', () => {
+        expect(resolveProxy({ enabled: false })).toBeNull();
+    });
+    it('returns null and warns when env vars are missing', () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        const result = resolveProxy({ enabled: true });
+        expect(result).toBeNull();
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('credentials not configured'));
+        warnSpy.mockRestore();
+    });
+    it('resolves proxy when env vars are set', () => {
+        process.env.SHOWRUN_PROXY_USERNAME = 'myuser';
+        process.env.SHOWRUN_PROXY_PASSWORD = 'mypass';
+        const result = resolveProxy({ enabled: true, mode: 'random' });
+        expect(result).not.toBeNull();
+        expect(result.server).toBe('http://pr.oxylabs.io:7777');
+        expect(result.username).toBe('customer-myuser');
+        expect(result.password).toBe('mypass');
+    });
+    it('reads provider from env var', () => {
+        process.env.SHOWRUN_PROXY_USERNAME = 'user';
+        process.env.SHOWRUN_PROXY_PASSWORD = 'pass';
+        process.env.SHOWRUN_PROXY_PROVIDER = 'oxylabs';
+        const result = resolveProxy({ enabled: true, mode: 'random' });
+        expect(result).not.toBeNull();
+    });
+    it('throws for unknown provider', () => {
+        process.env.SHOWRUN_PROXY_USERNAME = 'user';
+        process.env.SHOWRUN_PROXY_PASSWORD = 'pass';
+        expect(() => resolveProxy({ enabled: true, provider: 'nonexistent' })).toThrow('Unknown proxy provider "nonexistent"');
+    });
+});
+describe('provider registry', () => {
+    it('lists default providers', () => {
+        const names = listProxyProviders();
+        expect(names).toContain('oxylabs');
+    });
+    it('gets a provider by name', () => {
+        const provider = getProxyProvider('oxylabs');
+        expect(provider).toBeDefined();
+        expect(provider.name).toBe('oxylabs');
+    });
+    it('registers a custom provider', () => {
+        const custom = {
+            name: 'custom-test',
+            resolve(_config, creds) {
+                return { server: 'http://custom:1234', username: creds.username, password: creds.password };
+            },
+            requiredCredentialKeys() {
+                return ['USERNAME', 'PASSWORD'];
+            },
+        };
+        registerProxyProvider(custom);
+        expect(getProxyProvider('custom-test')).toBe(custom);
+        expect(listProxyProviders()).toContain('custom-test');
+    });
+});

package/dist/__tests__/registry-client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=registry-client.test.d.ts.map

package/dist/__tests__/registry-client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-client.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/registry-client.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/registry-client.test.js

@@ -0,0 +1,228 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, rmSync, statSync } from 'fs';
+import { join } from 'path';
+import { tmpdir, platform } from 'os';
+import { randomBytes } from 'crypto';
+// ── Token store tests ─────────────────────────────────────────────────────
+describe('tokenStore', () => {
+    let tempDir;
+    let originalEnv;
+    beforeEach(() => {
+        tempDir = join(tmpdir(), `showrun-test-${randomBytes(6).toString('hex')}`);
+        mkdirSync(tempDir, { recursive: true });
+        originalEnv = {
+            XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
+            APPDATA: process.env.APPDATA,
+            HOME: process.env.HOME,
+        };
+        // Point config dir to temp
+        process.env.XDG_CONFIG_HOME = tempDir;
+    });
+    afterEach(() => {
+        // Restore env
+        for (const [key, value] of Object.entries(originalEnv)) {
+            if (value === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = value;
+            }
+        }
+        // Clean up temp dir
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore
+        }
+        vi.restoreAllMocks();
+    });
+    it('saveTokens creates auth.json and loadTokens reads it', async () => {
+        const { saveTokens, loadTokens } = await import('../registry/tokenStore.js');
+        const auth = {
+            accessToken: 'at-123',
+            refreshToken: 'rt-456',
+            user: { id: '1', username: 'testuser', email: 'test@test.com' },
+            registryUrl: 'https://registry.example.com',
+            savedAt: new Date().toISOString(),
+        };
+        saveTokens(auth);
+        const loaded = loadTokens();
+        expect(loaded).not.toBeNull();
+        expect(loaded.accessToken).toBe('at-123');
+        expect(loaded.refreshToken).toBe('rt-456');
+        expect(loaded.user.username).toBe('testuser');
+        expect(loaded.registryUrl).toBe('https://registry.example.com');
+    });
+    it('clearTokens removes auth.json', async () => {
+        const { saveTokens, clearTokens, loadTokens } = await import('../registry/tokenStore.js');
+        saveTokens({
+            accessToken: 'at',
+            refreshToken: 'rt',
+            user: { id: '1', username: 'u', email: 'e@e.com' },
+            registryUrl: 'https://r.com',
+            savedAt: new Date().toISOString(),
+        });
+        expect(loadTokens()).not.toBeNull();
+        clearTokens();
+        expect(loadTokens()).toBeNull();
+    });
+    it('loadTokens returns null when no file exists', async () => {
+        const { loadTokens } = await import('../registry/tokenStore.js');
+        expect(loadTokens()).toBeNull();
+    });
+    it('sets 0o600 permissions on Unix', async () => {
+        if (platform() === 'win32')
+            return; // Skip on Windows
+        const { saveTokens } = await import('../registry/tokenStore.js');
+        saveTokens({
+            accessToken: 'at',
+            refreshToken: 'rt',
+            user: { id: '1', username: 'u', email: 'e@e.com' },
+            registryUrl: 'https://r.com',
+            savedAt: new Date().toISOString(),
+        });
+        const authPath = join(tempDir, 'showrun', 'auth.json');
+        const stats = statSync(authPath);
+        // 0o600 = owner read+write only
+        expect(stats.mode & 0o777).toBe(0o600);
+    });
+});
+// ── RegistryClient tests ──────────────────────────────────────────────────
+describe('RegistryClient', () => {
+    let originalEnv;
+    beforeEach(() => {
+        originalEnv = {
+            SHOWRUN_REGISTRY_URL: process.env.SHOWRUN_REGISTRY_URL,
+        };
+    });
+    afterEach(() => {
+        for (const [key, value] of Object.entries(originalEnv)) {
+            if (value === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = value;
+            }
+        }
+        vi.restoreAllMocks();
+    });
+    it('throws RegistryError when registry URL is not configured', async () => {
+        delete process.env.SHOWRUN_REGISTRY_URL;
+        const { RegistryClient, RegistryError } = await import('../registry/client.js');
+        expect(() => new RegistryClient()).toThrow(RegistryError);
+        expect(() => new RegistryClient()).toThrow('Registry not configured');
+    });
+    it('constructs with explicit URL', async () => {
+        const { RegistryClient } = await import('../registry/client.js');
+        const client = new RegistryClient('https://registry.example.com');
+        expect(client).toBeDefined();
+    });
+    it('constructs with env var', async () => {
+        process.env.SHOWRUN_REGISTRY_URL = 'https://registry.example.com';
+        const { RegistryClient } = await import('../registry/client.js');
+        const client = new RegistryClient();
+        expect(client).toBeDefined();
+    });
+    it('strips trailing slash from URL', async () => {
+        const { RegistryClient } = await import('../registry/client.js');
+        // The URL gets stripped internally - verify it works by checking search constructs properly
+        const client = new RegistryClient('https://registry.example.com///');
+        expect(client).toBeDefined();
+    });
+    it('startDeviceLogin requests device code', async () => {
+        const { RegistryClient } = await import('../registry/client.js');
+        const mockDevice = {
+            deviceCode: 'dc-123',
+            userCode: 'ABCD-1234',
+            verificationUri: 'https://registry.example.com/device',
+            expiresIn: 900,
+            interval: 5,
+        };
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(new Response(JSON.stringify(mockDevice), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+        }));
+        const client = new RegistryClient('https://registry.example.com');
+        const result = await client.startDeviceLogin();
+        expect(result.userCode).toBe('ABCD-1234');
+        expect(result.deviceCode).toBe('dc-123');
+        expect(fetchSpy).toHaveBeenCalledOnce();
+        expect(fetchSpy.mock.calls[0][0]).toBe('https://registry.example.com/api/auth/device');
+    });
+    it('pollDeviceLogin returns pending when user has not approved', async () => {
+        const { RegistryClient } = await import('../registry/client.js');
+        vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(new Response(JSON.stringify({ error: 'authorization_pending' }), {
+            status: 428,
+            headers: { 'Content-Type': 'application/json' },
+        }));
+        const client = new RegistryClient('https://registry.example.com');
+        const result = await client.pollDeviceLogin('dc-123');
+        expect(result.status).toBe('pending');
+    });
+    it('pollDeviceLogin stores tokens on success', async () => {
+        const { RegistryClient } = await import('../registry/client.js');
+        const { loadTokens, clearTokens } = await import('../registry/tokenStore.js');
+        const mockTokenResponse = {
+            accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjk5OTk5OTk5OTl9.test',
+            refreshToken: 'rt-mock',
+            user: { id: '1', username: 'mockuser', email: 'mock@test.com', displayName: 'Mock User' },
+        };
+        vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(new Response(JSON.stringify(mockTokenResponse), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+        }));
+        const client = new RegistryClient('https://registry.example.com');
+        const result = await client.pollDeviceLogin('dc-123');
+        expect(result.status).toBe('complete');
+        if (result.status === 'complete') {
+            expect(result.user.username).toBe('mockuser');
+        }
+        // Verify tokens were stored
+        const stored = loadTokens();
+        expect(stored).not.toBeNull();
+        expect(stored.accessToken).toBe(mockTokenResponse.accessToken);
+        // Clean up
+        clearTokens();
+    });
+    it('searchPacks sends correct query params', async () => {
+        const { RegistryClient } = await import('../registry/client.js');
+        const mockResponse = {
+            data: [],
+            total: 0,
+            page: 1,
+            limit: 20,
+            totalPages: 0,
+        };
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(new Response(JSON.stringify(mockResponse), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+        }));
+        const client = new RegistryClient('https://registry.example.com');
+        await client.searchPacks({ q: 'test', page: 2, limit: 10 });
+        expect(fetchSpy).toHaveBeenCalledOnce();
+        const url = fetchSpy.mock.calls[0][0];
+        expect(url).toContain('/api/packs?');
+        expect(url).toContain('q=test');
+        expect(url).toContain('page=2');
+        expect(url).toContain('limit=10');
+    });
+    it('handles 4xx/5xx errors as RegistryError', async () => {
+        const { RegistryClient, RegistryError } = await import('../registry/client.js');
+        vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(new Response(JSON.stringify({ message: 'Not Found' }), {
+            status: 404,
+            headers: { 'Content-Type': 'application/json' },
+        }));
+        const client = new RegistryClient('https://registry.example.com');
+        await expect(client.searchPacks({ q: 'missing' })).rejects.toThrow(RegistryError);
+        await expect(
+        // Re-mock for second call
+        (async () => {
+            vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(new Response(JSON.stringify({ message: 'Internal error' }), {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' },
+            }));
+            return client.searchPacks({ q: 'fail' });
+        })()).rejects.toThrow(RegistryError);
+    });
+});

package/dist/browserLauncher.d.ts

@@ -6,6 +6,7 @@
  */
 import { type Browser, type BrowserContext, type Page } from 'playwright';
 import type { BrowserEngine, BrowserSettings, BrowserPersistence } from './types.js';
+import type { ResolvedProxy } from './proxy/types.js';
 /**
  * Browser session returned by launchBrowser
  */
@@ -34,6 +35,10 @@ export interface BrowserSession {
      * User data directory path (if persistence is enabled)
      */
     userDataDir?: string;
+    /**
+     * Resolved proxy used for this session (if any)
+     */
+    proxy?: ResolvedProxy;
     /**
      * Close the browser session
      */
@@ -64,6 +69,17 @@ export interface LaunchBrowserConfig {
      * When set, bypasses persistence resolution (sessionId/packPath).
      */
     userDataDir?: string;
+    /**
+     * Resolved proxy to route traffic through.
+     * Passed directly to Playwright/Camoufox launch options.
+     */
+    proxy?: ResolvedProxy;
+    /**
+     * Chrome DevTools Protocol URL to connect to an existing browser.
+     * When set, connects via CDP instead of launching a new browser.
+     * Chromium-only (Camoufox/Firefox does not support CDP).
+     */
+    cdpUrl?: string;
 }
 /**
  * Launches a browser with the specified configuration

package/dist/browserLauncher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browserLauncher.d.ts","sourceRoot":"","sources":["../src/browserLauncher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAY,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAGpF,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,cAAc,CAAC;IACxB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;IACX;;OAEG;IACH,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB;;OAEG;IACH,WAAW,EAAE,kBAAkB,CAAC;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CA0CxF;AA6JD;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBtF"}
+{"version":3,"file":"browserLauncher.d.ts","sourceRoot":"","sources":["../src/browserLauncher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAY,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAGpF,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,cAAc,CAAC;IACxB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;IACX;;OAEG;IACH,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB;;OAEG;IACH,WAAW,EAAE,kBAAkB,CAAC;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAiDxF;AAyMD;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBtF"}