@showrun/core 0.1.7 → 0.1.9

package/dist/dsl/validation.js

@@ -235,6 +235,7 @@ const ALLOWED_PARAMS = {
     frame: ['frame', 'action'],
     new_tab: ['url', 'saveTabIndexAs'],
     switch_tab: ['tab', 'closeCurrentTab'],
+    dom_scrape: ['selector', 'target', 'collect', 'skip_empty', 'out', 'hint', 'scope', 'near'],
 };
 /**
  * Validates a single step, pushing errors to the array.
@@ -922,8 +923,96 @@ function validateStep(step, stepIndex, errors) {
                 errors.push(`${prefix}: SwitchTab step "closeCurrentTab" must be a boolean`);
             }
             break;
+        case 'dom_scrape': {
+            // Must have either selector (legacy) or target (new)
+            if (!params.selector && !params.target) {
+                errors.push(`${prefix}: DomScrape step must have either "selector" or "target" in params`);
+            }
+            if (params.selector !== undefined && typeof params.selector !== 'string') {
+                errors.push(`${prefix}: DomScrape step "selector" must be a string`);
+            }
+            if (params.target !== undefined) {
+                validateTargetOrAnyOf(params.target, errors, prefix);
+            }
+            if (typeof params.out !== 'string' || !params.out) {
+                errors.push(`${prefix}: DomScrape step must have a non-empty string "out" in params`);
+            }
+            if (!Array.isArray(params.collect) || params.collect.length === 0) {
+                errors.push(`${prefix}: DomScrape step must have a non-empty "collect" array in params`);
+            }
+            else {
+                const seenKeys = new Set();
+                const ALLOWED_COLLECT_FIELDS = new Set(['key', 'target', 'extract', 'attribute']);
+                for (let ci = 0; ci < params.collect.length; ci++) {
+                    const field = params.collect[ci];
+                    if (!field || typeof field !== 'object') {
+                        errors.push(`${prefix}: DomScrape collect[${ci}] must be an object`);
+                        continue;
+                    }
+                    const f = field;
+                    // Check for unknown fields
+                    const unknownFields = Object.keys(f).filter(k => !ALLOWED_COLLECT_FIELDS.has(k));
+                    if (unknownFields.length > 0) {
+                        errors.push(`${prefix}: DomScrape collect[${ci}] has unknown field(s): ${unknownFields.map(k => `"${k}"`).join(', ')}. Allowed: key, target, extract, attribute`);
+                    }
+                    // key
+                    if (typeof f.key !== 'string' || !f.key) {
+                        errors.push(`${prefix}: DomScrape collect[${ci}] must have a non-empty string "key"`);
+                    }
+                    else {
+                        if (seenKeys.has(f.key)) {
+                            errors.push(`${prefix}: DomScrape collect has duplicate key "${f.key}"`);
+                        }
+                        seenKeys.add(f.key);
+                    }
+                    // target
+                    if (!f.target) {
+                        errors.push(`${prefix}: DomScrape collect[${ci}] must have a "target"`);
+                    }
+                    else {
+                        validateTarget(f.target, errors, `${prefix} collect[${ci}]`);
+                    }
+                    // extract
+                    if (f.extract !== undefined) {
+                        if (f.extract !== 'text' && f.extract !== 'attribute' && f.extract !== 'html') {
+                            errors.push(`${prefix}: DomScrape collect[${ci}] "extract" must be "text", "attribute", or "html"`);
+                        }
+                    }
+                    // attribute required when extract === 'attribute'
+                    if (f.extract === 'attribute') {
+                        if (typeof f.attribute !== 'string' || !f.attribute) {
+                            errors.push(`${prefix}: DomScrape collect[${ci}] requires "attribute" when extract is "attribute"`);
+                        }
+                    }
+                }
+            }
+            if (params.skip_empty !== undefined && typeof params.skip_empty !== 'boolean') {
+                errors.push(`${prefix}: DomScrape step "skip_empty" must be a boolean`);
+            }
+            if (params.hint !== undefined && typeof params.hint !== 'string') {
+                errors.push(`${prefix}: DomScrape step "hint" must be a string`);
+            }
+            if (params.scope !== undefined) {
+                validateTarget(params.scope, errors, prefix);
+            }
+            if (params.near !== undefined && params.near !== null) {
+                const near = params.near;
+                if (typeof near !== 'object' || near.kind !== 'text') {
+                    errors.push(`${prefix}: DomScrape step "near" must be an object with kind: "text"`);
+                }
+                else {
+                    if (typeof near.text !== 'string') {
+                        errors.push(`${prefix}: DomScrape step "near.text" must be a string`);
+                    }
+                    if (near.exact !== undefined && typeof near.exact !== 'boolean') {
+                        errors.push(`${prefix}: DomScrape step "near.exact" must be a boolean`);
+                    }
+                }
+            }
+            break;
+        }
         default:
-            errors.push(`${prefix}: Unknown step type: ${s.type}. Supported types: navigate, extract_title, extract_text, extract_attribute, sleep, wait_for, click, fill, assert, set_var, network_find, network_replay, network_extract, select_option, press_key, upload_file, frame, new_tab, switch_tab`);
+            errors.push(`${prefix}: Unknown step type: ${s.type}. Supported types: navigate, extract_title, extract_text, extract_attribute, sleep, wait_for, click, fill, assert, set_var, network_find, network_replay, network_extract, select_option, press_key, upload_file, frame, new_tab, switch_tab, dom_scrape`);
     }
     // Check for unknown params
     const allowed = ALLOWED_PARAMS[s.type];

package/dist/httpReplay.d.ts

@@ -7,6 +7,7 @@
  */
 import type { DslStep } from './dsl/types.js';
 import { type RequestSnapshot, type SnapshotFile, type ValidationResult } from './requestSnapshot.js';
+import type { ResolvedProxy } from './proxy/types.js';
 export interface HttpReplayResult {
     status: number;
     contentType?: string;
@@ -19,6 +20,8 @@ export interface HttpReplayResult {
  * Requirements:
  * 1. Every `network_replay` step has a corresponding, non-stale snapshot.
  * 2. No DOM extraction steps exist in the flow.
+ * 3. No skipped steps contain dynamic templates — templates in skipped steps
+ *    would never be evaluated, so the snapshot replays stale data.
  */
 export declare function isFlowHttpCompatible(steps: DslStep[], snapshots: SnapshotFile | null): boolean;
 /**
@@ -28,6 +31,7 @@ export declare function isFlowHttpCompatible(steps: DslStep[], snapshots: Snapsh
 export declare function replayFromSnapshot(snapshot: RequestSnapshot, inputs: Record<string, unknown>, vars: Record<string, unknown>, options?: {
     secrets?: Record<string, string>;
     timeoutMs?: number;
+    proxy?: ResolvedProxy;
 }): Promise<HttpReplayResult>;
 /**
  * Replay a snapshot and validate the response.
@@ -36,6 +40,7 @@ export declare function replayFromSnapshot(snapshot: RequestSnapshot, inputs: Re
 export declare function replayAndValidate(snapshot: RequestSnapshot, inputs: Record<string, unknown>, vars: Record<string, unknown>, options?: {
     secrets?: Record<string, string>;
     timeoutMs?: number;
+    proxy?: ResolvedProxy;
 }): Promise<{
     result: HttpReplayResult;
     validation: ValidationResult;

package/dist/httpReplay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"httpReplay.d.ts","sourceRoot":"","sources":["../src/httpReplay.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EAIjB,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAa9B,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AASD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EAAE,EAChB,SAAS,EAAE,YAAY,GAAG,IAAI,GAC7B,OAAO,CAqBT;AAMD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACjE,OAAO,CAAC,gBAAgB,CAAC,CA0C3B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACjE,OAAO,CAAC;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAIrE"}
+{"version":3,"file":"httpReplay.d.ts","sourceRoot":"","sources":["../src/httpReplay.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EAIjB,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAatD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EAAE,EAChB,SAAS,EAAE,YAAY,GAAG,IAAI,GAC7B,OAAO,CA4BT;AAMD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAAE,GACxF,OAAO,CAAC,gBAAgB,CAAC,CA6D3B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAAE,GACxF,OAAO,CAAC;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAIrE"}

package/dist/httpReplay.js

@@ -15,22 +15,50 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 // HTTP-only compatibility check
 // ---------------------------------------------------------------------------
 /** Step types that require DOM access for data extraction (force browser mode). */
-const DOM_EXTRACTION_STEPS = new Set(['extract_text', 'extract_title', 'extract_attribute']);
+const DOM_EXTRACTION_STEPS = new Set(['extract_text', 'extract_title', 'extract_attribute', 'dom_scrape']);
+/**
+ * Step types that are silently skipped in HTTP mode.
+ * Must match HTTP_MODE_SKIP_STEPS in stepHandlers.ts.
+ */
+const HTTP_SKIPPED_STEPS = new Set([
+    'navigate', 'click', 'fill', 'select_option', 'press_key',
+    'upload_file', 'wait_for', 'assert', 'frame', 'new_tab',
+    'switch_tab', 'network_find', 'dom_scrape',
+]);
+/** Check if a value contains Nunjucks template expressions. */
+function containsTemplate(value) {
+    if (typeof value === 'string')
+        return value.includes('{{');
+    if (Array.isArray(value))
+        return value.some(containsTemplate);
+    if (value && typeof value === 'object') {
+        return Object.values(value).some(containsTemplate);
+    }
+    return false;
+}
 /**
  * Check whether a flow can run in HTTP-only mode.
  *
  * Requirements:
  * 1. Every `network_replay` step has a corresponding, non-stale snapshot.
  * 2. No DOM extraction steps exist in the flow.
+ * 3. No skipped steps contain dynamic templates — templates in skipped steps
+ *    would never be evaluated, so the snapshot replays stale data.
  */
 export function isFlowHttpCompatible(steps, snapshots) {
     if (!snapshots)
         return false;
-    // Check for DOM extraction steps
     for (const step of steps) {
+        // DOM extraction steps force browser mode
         if (DOM_EXTRACTION_STEPS.has(step.type)) {
             return false;
         }
+        // Steps skipped in HTTP mode must not contain templates — those templates
+        // affect what data the API returns but would never be evaluated, causing
+        // the snapshot to replay stale/wrong data regardless of input values.
+        if (HTTP_SKIPPED_STEPS.has(step.type) && containsTemplate(step.params)) {
+            return false;
+        }
     }
     // Check that every network_replay step has a valid snapshot
     const replaySteps = steps.filter((s) => s.type === 'network_replay');
@@ -70,6 +98,22 @@ export async function replayFromSnapshot(snapshot, inputs, vars, options) {
     if (body && method !== 'GET' && method !== 'HEAD') {
         fetchOptions.body = body;
     }
+    // When proxy is provided, create a ProxyAgent dispatcher for undici-backed fetch.
+    // undici is bundled with Node but may not have separate type declarations.
+    if (options?.proxy) {
+        try {
+            // @ts-expect-error undici types may not be installed; runtime import is fine
+            const undiciModule = await import('undici');
+            const ProxyAgentClass = undiciModule.ProxyAgent;
+            if (ProxyAgentClass) {
+                const proxyUrl = options.proxy.server.replace('://', `://${encodeURIComponent(options.proxy.username)}:${encodeURIComponent(options.proxy.password)}@`);
+                fetchOptions.dispatcher = new ProxyAgentClass(proxyUrl);
+            }
+        }
+        catch {
+            console.warn('[httpReplay] Failed to load undici ProxyAgent, making direct request');
+        }
+    }
     try {
         const response = await fetch(url, fetchOptions);
         const responseBody = await response.text();

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './packVersioning.js';
 export * from './config.js';
 export * from './requestSnapshot.js';
 export * from './httpReplay.js';
+export * from './proxy/index.js';
 export * from './storage/index.js';
 export * from './dsl/types.js';
 export * from './dsl/builders.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -13,6 +13,8 @@ export * from './packVersioning.js';
 export * from './config.js';
 export * from './requestSnapshot.js';
 export * from './httpReplay.js';
+// Proxy exports
+export * from './proxy/index.js';
 // Storage exports
 export * from './storage/index.js';
 // DSL exports

package/dist/jsonPackValidator.js

@@ -2,7 +2,7 @@ import { validateFlow, ValidationError } from './dsl/validation.js';
 /** Step types that produce collectible output via an "out" parameter */
 const STEPS_WITH_OUT = new Set([
     'extract_title', 'extract_text', 'extract_attribute',
-    'network_replay', 'network_extract',
+    'network_replay', 'network_extract', 'dom_scrape',
 ]);
 /**
  * Validates that collectibles referenced in flow steps exist

package/dist/proxy/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './oxylabs.js';
+export * from './proxyService.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/proxy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/proxy/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC"}

package/dist/proxy/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './oxylabs.js';
+export * from './proxyService.js';

package/dist/proxy/oxylabs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OxyLabs residential proxy provider.
+ *
+ * Endpoint: pr.oxylabs.io:7777
+ * Username format:
+ *   Random: customer-{USERNAME}[-cc-{COUNTRY}]
+ *   Session: customer-{USERNAME}[-cc-{COUNTRY}]-sessid-{UUID}-sesstime-{MIN}
+ */
+import type { ProxyConfig, ProxyCredentials, ProxyProvider, ResolvedProxy } from './types.js';
+export declare class OxylabsProvider implements ProxyProvider {
+    readonly name = "oxylabs";
+    resolve(config: ProxyConfig, credentials: ProxyCredentials): ResolvedProxy;
+    requiredCredentialKeys(): string[];
+}
+//# sourceMappingURL=oxylabs.d.ts.map

package/dist/proxy/oxylabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oxylabs.d.ts","sourceRoot":"","sources":["../../src/proxy/oxylabs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK9F,qBAAa,eAAgB,YAAW,aAAa;IACnD,QAAQ,CAAC,IAAI,aAAa;IAE1B,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,GAAG,aAAa;IAqB1E,sBAAsB,IAAI,MAAM,EAAE;CAGnC"}

package/dist/proxy/oxylabs.js

@@ -0,0 +1,34 @@
+/**
+ * OxyLabs residential proxy provider.
+ *
+ * Endpoint: pr.oxylabs.io:7777
+ * Username format:
+ *   Random: customer-{USERNAME}[-cc-{COUNTRY}]
+ *   Session: customer-{USERNAME}[-cc-{COUNTRY}]-sessid-{UUID}-sesstime-{MIN}
+ */
+import { randomUUID } from 'crypto';
+const OXYLABS_ENDPOINT = 'http://pr.oxylabs.io:7777';
+const DEFAULT_SESSION_DURATION_MINUTES = 10;
+export class OxylabsProvider {
+    name = 'oxylabs';
+    resolve(config, credentials) {
+        const mode = config.mode ?? 'session';
+        let username = `customer-${credentials.username}`;
+        if (config.country) {
+            username += `-cc-${config.country.toUpperCase()}`;
+        }
+        if (mode === 'session') {
+            const sessionId = randomUUID().replace(/-/g, '');
+            const duration = config.sessionDurationMinutes ?? DEFAULT_SESSION_DURATION_MINUTES;
+            username += `-sessid-${sessionId}-sesstime-${duration}`;
+        }
+        return {
+            server: OXYLABS_ENDPOINT,
+            username,
+            password: credentials.password,
+        };
+    }
+    requiredCredentialKeys() {
+        return ['USERNAME', 'PASSWORD'];
+    }
+}

package/dist/proxy/proxyService.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Proxy service: provider registry and resolution.
+ *
+ * Reads credentials from environment variables:
+ *   SHOWRUN_PROXY_USERNAME, SHOWRUN_PROXY_PASSWORD
+ * Provider from config or SHOWRUN_PROXY_PROVIDER env var (default: 'oxylabs').
+ *
+ * Graceful fallback: if env vars are missing, returns null (no proxy) instead of throwing.
+ */
+import type { ProxyConfig, ProxyProvider, ResolvedProxy } from './types.js';
+/**
+ * Register a custom proxy provider.
+ */
+export declare function registerProxyProvider(provider: ProxyProvider): void;
+/**
+ * Get a registered proxy provider by name.
+ */
+export declare function getProxyProvider(name: string): ProxyProvider | undefined;
+/**
+ * List all registered proxy provider names.
+ */
+export declare function listProxyProviders(): string[];
+/**
+ * Resolve a proxy configuration into concrete connection details.
+ *
+ * Returns `null` when:
+ * - config is undefined or disabled
+ * - required env vars are missing (graceful fallback, logs warning)
+ *
+ * Throws when:
+ * - provider name is unknown
+ */
+export declare function resolveProxy(config: ProxyConfig | undefined): ResolvedProxy | null;
+//# sourceMappingURL=proxyService.d.ts.map

package/dist/proxy/proxyService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxyService.d.ts","sourceRoot":"","sources":["../../src/proxy/proxyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAoB,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAW9F;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAEnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAExE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAaD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,IAAI,CAsBlF"}

package/dist/proxy/proxyService.js

@@ -0,0 +1,69 @@
+/**
+ * Proxy service: provider registry and resolution.
+ *
+ * Reads credentials from environment variables:
+ *   SHOWRUN_PROXY_USERNAME, SHOWRUN_PROXY_PASSWORD
+ * Provider from config or SHOWRUN_PROXY_PROVIDER env var (default: 'oxylabs').
+ *
+ * Graceful fallback: if env vars are missing, returns null (no proxy) instead of throwing.
+ */
+import { OxylabsProvider } from './oxylabs.js';
+// ── Provider registry ──────────────────────────────────────────────────
+const providers = new Map();
+// Register OxyLabs by default
+const defaultProvider = new OxylabsProvider();
+providers.set(defaultProvider.name, defaultProvider);
+/**
+ * Register a custom proxy provider.
+ */
+export function registerProxyProvider(provider) {
+    providers.set(provider.name, provider);
+}
+/**
+ * Get a registered proxy provider by name.
+ */
+export function getProxyProvider(name) {
+    return providers.get(name);
+}
+/**
+ * List all registered proxy provider names.
+ */
+export function listProxyProviders() {
+    return [...providers.keys()];
+}
+// ── Credential helpers ─────────────────────────────────────────────────
+function readCredentialsFromEnv() {
+    const username = process.env.SHOWRUN_PROXY_USERNAME;
+    const password = process.env.SHOWRUN_PROXY_PASSWORD;
+    if (!username || !password)
+        return null;
+    return { username, password };
+}
+// ── Resolution ─────────────────────────────────────────────────────────
+/**
+ * Resolve a proxy configuration into concrete connection details.
+ *
+ * Returns `null` when:
+ * - config is undefined or disabled
+ * - required env vars are missing (graceful fallback, logs warning)
+ *
+ * Throws when:
+ * - provider name is unknown
+ */
+export function resolveProxy(config) {
+    if (!config || !config.enabled)
+        return null;
+    const providerName = config.provider ?? process.env.SHOWRUN_PROXY_PROVIDER ?? 'oxylabs';
+    const provider = providers.get(providerName);
+    if (!provider) {
+        throw new Error(`Unknown proxy provider "${providerName}". Registered providers: ${listProxyProviders().join(', ')}`);
+    }
+    const credentials = readCredentialsFromEnv();
+    if (!credentials) {
+        console.warn(`[proxy] Proxy enabled but credentials not configured. ` +
+            `Set SHOWRUN_PROXY_USERNAME and SHOWRUN_PROXY_PASSWORD environment variables. ` +
+            `Running without proxy.`);
+        return null;
+    }
+    return provider.resolve(config, credentials);
+}

package/dist/proxy/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Proxy configuration types for browser and HTTP request proxying.
+ */
+/**
+ * Proxy mode determines how proxy sessions are managed:
+ * - 'session': Sticky IP for the duration of the session (default)
+ * - 'random': Rotating IP per request
+ */
+export type ProxyMode = 'session' | 'random';
+/**
+ * Proxy configuration stored in taskpack.json under `browser.proxy`.
+ * Persisted by the agent's `set_proxy` tool.
+ */
+export interface ProxyConfig {
+    /** Whether proxy is enabled */
+    enabled: boolean;
+    /** Proxy mode: sticky session or random rotation */
+    mode?: ProxyMode;
+    /** Provider name (default: 'oxylabs') */
+    provider?: string;
+    /** Two-letter ISO country code for geo-targeting */
+    country?: string;
+    /** Session duration in minutes (for session mode) */
+    sessionDurationMinutes?: number;
+}
+/**
+ * Resolved proxy credentials ready for Playwright / fetch.
+ * Maps directly to Playwright's `proxy` launch option.
+ */
+export interface ResolvedProxy {
+    server: string;
+    username: string;
+    password: string;
+}
+/**
+ * Credentials supplied to a proxy provider (from env vars).
+ */
+export interface ProxyCredentials {
+    username: string;
+    password: string;
+}
+/**
+ * Interface for pluggable proxy providers.
+ * Implement this to add support for a new proxy service.
+ */
+export interface ProxyProvider {
+    /** Provider name (e.g. 'oxylabs') */
+    readonly name: string;
+    /**
+     * Resolve proxy config + credentials into a concrete proxy connection.
+     */
+    resolve(config: ProxyConfig, credentials: ProxyCredentials): ResolvedProxy;
+    /**
+     * List of env var suffixes this provider needs (for display/validation).
+     * e.g. ['USERNAME', 'PASSWORD'] → expects SHOWRUN_PROXY_USERNAME, SHOWRUN_PROXY_PASSWORD
+     */
+    requiredCredentialKeys(): string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/proxy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/proxy/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,GAAG,aAAa,CAAC;IAE3E;;;OAGG;IACH,sBAAsB,IAAI,MAAM,EAAE,CAAC;CACpC"}

package/dist/proxy/types.js

@@ -0,0 +1,4 @@
+/**
+ * Proxy configuration types for browser and HTTP request proxying.
+ */
+export {};

package/dist/registry/client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Registry client for ShowRun pack registry.
+ *
+ * Communicates with the registry REST API to authenticate, publish, search,
+ * and install task packs. Uses the global token store for persistence and
+ * automatically refreshes access tokens before they expire.
+ */
+import type { IRegistryClient, DeviceCodeResponse, DevicePollResult, UserProfile, PublishParams, PublishResult, PackSummary, PaginatedResponse, SearchQuery } from './types.js';
+export declare class RegistryError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+export declare class RegistryClient implements IRegistryClient {
+    private readonly registryUrl;
+    constructor(registryUrl?: string);
+    startDeviceLogin(): Promise<DeviceCodeResponse>;
+    pollDeviceLogin(deviceCode: string): Promise<DevicePollResult>;
+    logout(): Promise<void>;
+    whoami(): Promise<UserProfile>;
+    isAuthenticated(): boolean;
+    publishPack(params: PublishParams): Promise<PublishResult>;
+    searchPacks(query: SearchQuery): Promise<PaginatedResponse<PackSummary>>;
+    installPack(slug: string, destDir: string, version?: string): Promise<void>;
+    private request;
+    /**
+     * Get a valid access token, refreshing if it's about to expire (within 60s).
+     * If refresh fails, clears tokens and throws.
+     */
+    private getValidAccessToken;
+    private refreshAccessToken;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/registry/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/registry/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAGhB,WAAW,EACX,aAAa,EACb,aAAa,EACb,WAAW,EAEX,iBAAiB,EACjB,WAAW,EAEZ,MAAM,YAAY,CAAC;AAMpB,qBAAa,aAAc,SAAQ,KAAK;aAGpB,MAAM,EAAE,MAAM;aACd,IAAI,CAAC,EAAE,OAAO;gBAF9B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,YAAA;CAKjC;AAwBD,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,WAAW,CAAC,EAAE,MAAM;IAc1B,gBAAgB,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAS/C,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+C9D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvB,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC;IAIpC,eAAe,IAAI,OAAO;IAOpB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAiE1D,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAWxE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YA0BnE,OAAO;IAwCrB;;;OAGG;YACW,mBAAmB;YAkCnB,kBAAkB;CAcjC"}