@taodigital/crawler 0.0.0-stage → 1.2.1

package/dist/skyvern.js

@@ -0,0 +1,129 @@
+async function skyvernNavigate(startUrl, navigationGoals, tenantConfig, triggerReason) {
+  const apiUrl = tenantConfig?.apiUrl || process.env.SKYVERN_API_URL;
+  const apiKey = tenantConfig?.apiKey || process.env.SKYVERN_API_KEY;
+  if (!apiUrl || !apiKey) {
+    console.warn("[skyvern] skyvernNavigate: no API config \u2014 skipping post-login vision navigation");
+    return { screenshotUrls: [], visitedUrls: [], status: "failed" };
+  }
+  const visitedUrls = [];
+  const screenshotUrls = [];
+  const skyvernSteps = [];
+  let lastTaskId;
+  let totalDurationMs = 0;
+  for (const goal of navigationGoals) {
+    try {
+      const taskStart = Date.now();
+      const res = await fetch(`${apiUrl}/api/v1/tasks`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "x-api-key": apiKey },
+        body: JSON.stringify({
+          url: startUrl,
+          navigation_goal: goal,
+          ...tenantConfig?.llmKey ? { llm_key: tenantConfig.llmKey } : process.env.SKYVERN_LLM_KEY ? { llm_key: process.env.SKYVERN_LLM_KEY } : {},
+          ...tenantConfig?.llmApiKey ? { llm_api_key: tenantConfig.llmApiKey } : process.env.OPENAI_API_KEY ? { llm_api_key: process.env.OPENAI_API_KEY } : {}
+        })
+      });
+      if (!res.ok) continue;
+      const data = await res.json();
+      const taskId = data.task_id;
+      if (!taskId) continue;
+      lastTaskId = taskId;
+      let done = false;
+      for (let p = 0; p < 12 && !done; p++) {
+        await new Promise((r) => setTimeout(r, 5e3));
+        const poll = await fetch(`${apiUrl}/api/v1/tasks/${taskId}`, {
+          headers: { "x-api-key": apiKey }
+        }).catch(() => null);
+        if (!poll?.ok) continue;
+        const pollData = await poll.json();
+        if (pollData.status === "completed" || pollData.status === "failed") {
+          done = true;
+          totalDurationMs += Date.now() - taskStart;
+          if (pollData.status === "completed") {
+            if (pollData.output?.url) visitedUrls.push(pollData.output.url);
+            if (pollData.output?.screenshot_url) screenshotUrls.push(pollData.output.screenshot_url);
+          }
+          try {
+            const stepsRes = await fetch(`${apiUrl}/api/v1/tasks/${taskId}/steps`, {
+              headers: { "x-api-key": apiKey }
+            }).catch(() => null);
+            if (stepsRes?.ok) {
+              const stepsData = await stepsRes.json();
+              const stepsList = Array.isArray(stepsData) ? stepsData : stepsData?.steps ?? [];
+              for (const s of stepsList) {
+                if (s.output?.screenshot_url) screenshotUrls.push(s.output.screenshot_url);
+                skyvernSteps.push({
+                  order: s.step_order ?? s.order ?? 0,
+                  action_type: s.action_type ?? s.action ?? "unknown",
+                  element_description: s.output?.element_description,
+                  reasoning: s.output?.llm_response?.action_description ?? s.output?.reasoning,
+                  success: s.status === "completed",
+                  screenshot_url: s.output?.screenshot_url,
+                  error: s.status === "failed" ? s.output?.errors?.[0] ?? "Step failed" : void 0
+                });
+              }
+            }
+          } catch {
+          }
+        }
+      }
+    } catch (err) {
+      console.warn(`[skyvern] Navigation goal failed: ${goal}`, err);
+    }
+  }
+  return {
+    screenshotUrls,
+    visitedUrls,
+    status: visitedUrls.length > 0 ? "success" : screenshotUrls.length > 0 ? "partial" : "failed",
+    steps: skyvernSteps,
+    taskId: lastTaskId,
+    durationMs: totalDurationMs || void 0,
+    triggerReason
+  };
+}
+async function skyvernFallback(task, tenantConfig) {
+  const apiUrl = tenantConfig?.apiUrl || process.env.SKYVERN_API_URL;
+  const apiKey = tenantConfig?.apiKey || process.env.SKYVERN_API_KEY;
+  if (!apiUrl || !apiKey) {
+    console.warn(
+      "[skyvern] Vision fallback disabled \u2014 set SKYVERN_API_URL + SKYVERN_API_KEY in .env to enable.",
+      "\n[skyvern] Self-host: https://github.com/Skyvern-AI/skyvern"
+    );
+    return "failed";
+  }
+  try {
+    const res = await fetch(`${apiUrl}/api/v1/tasks`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-api-key": apiKey },
+      body: JSON.stringify({
+        url: task.url,
+        navigation_goal: task.taskDescription,
+        ...task.credentials && {
+          navigation_payload: {
+            username: task.credentials.username,
+            password: task.credentials.password,
+            ...task.credentials.oneTimeCode && { otp: task.credentials.oneTimeCode }
+          }
+        },
+        ...tenantConfig?.llmKey ? { llm_key: tenantConfig.llmKey } : process.env.SKYVERN_LLM_KEY ? { llm_key: process.env.SKYVERN_LLM_KEY } : {},
+        ...tenantConfig?.llmApiKey ? { llm_api_key: tenantConfig.llmApiKey } : process.env.OPENAI_API_KEY ? { llm_api_key: process.env.OPENAI_API_KEY } : {}
+      })
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      console.error(`[skyvern] Task creation failed: ${res.status}`, body);
+      return "failed";
+    }
+    const data = await res.json();
+    console.log(`[skyvern] Task queued: ${data.task_id}. Poll GET /api/v1/tasks/${data.task_id} for completion.`);
+    return "success";
+  } catch (err) {
+    console.error("[skyvern] Error:", err);
+    return "failed";
+  }
+}
+export {
+  skyvernFallback,
+  skyvernNavigate
+};
+//# sourceMappingURL=skyvern.js.map

package/dist/skyvern.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/skyvern.ts"],
+  "sourcesContent": ["/**\n * Skyvern Vision Fallback\n *\n * Skyvern combines computer vision + LLM reasoning to navigate sites that\n * defeat DOM-based approaches: CAPTCHAs, legacy apps, visual-only login flows,\n * government portals. It's the \"break glass\" option when Stagehand fails.\n *\n * Production setup (Phase 4+):\n *   1. Self-host: https://github.com/Skyvern-AI/skyvern\n *   2. Or use cloud: https://app.skyvern.com\n *   3. Set SKYVERN_API_URL + SKYVERN_API_KEY in .env\n *\n * Pricing note: vision tasks cost more per step than DOM-based Stagehand.\n * Use only when the fast path fails.\n */\n\nexport interface SkyvernTask {\n  taskDescription: string;\n  url: string;\n  credentials?: { username: string; password: string; oneTimeCode?: string };\n}\n\nexport interface SkyvernConfig {\n  apiUrl: string;\n  apiKey: string;\n  llmKey?: string;\n  llmApiKey?: string;\n}\n\nexport interface SkyvernStep {\n  order: number;\n  action_type: string;\n  element_description?: string;\n  reasoning?: string;\n  success: boolean;\n  screenshot_url?: string;\n  duration_ms?: number;\n  error?: string;\n}\n\nexport interface SkyvernNavigateResult {\n  screenshotUrls: string[];\n  visitedUrls: string[];\n  status: 'success' | 'failed' | 'partial';\n  steps?: SkyvernStep[];\n  taskId?: string;\n  durationMs?: number;\n  triggerReason?: string;\n}\n\n/**\n * Gap 5: Post-login navigation via Skyvern vision for apps where DOM analysis\n * cannot discover screens (canvas, WebGL, legacy Flash-replacement stacks).\n * Skyvern drives the browser via screenshot + LLM, returning visited page list.\n */\nexport async function skyvernNavigate(\n  startUrl: string,\n  navigationGoals: string[],\n  tenantConfig?: SkyvernConfig,\n  triggerReason?: string,\n): Promise<SkyvernNavigateResult> {\n  const apiUrl = tenantConfig?.apiUrl || process.env.SKYVERN_API_URL;\n  const apiKey = tenantConfig?.apiKey || process.env.SKYVERN_API_KEY;\n\n  if (!apiUrl || !apiKey) {\n    console.warn('[skyvern] skyvernNavigate: no API config \u2014 skipping post-login vision navigation');\n    return { screenshotUrls: [], visitedUrls: [], status: 'failed' };\n  }\n\n  const visitedUrls: string[] = [];\n  const screenshotUrls: string[] = [];\n  const skyvernSteps: SkyvernStep[] = [];\n  let lastTaskId: string | undefined;\n  let totalDurationMs = 0;\n\n  for (const goal of navigationGoals) {\n    try {\n      const taskStart = Date.now();\n      const res = await fetch(`${apiUrl}/api/v1/tasks`, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },\n        body: JSON.stringify({\n          url: startUrl,\n          navigation_goal: goal,\n          ...(tenantConfig?.llmKey ? { llm_key: tenantConfig.llmKey } : process.env.SKYVERN_LLM_KEY ? { llm_key: process.env.SKYVERN_LLM_KEY } : {}),\n          ...(tenantConfig?.llmApiKey ? { llm_api_key: tenantConfig.llmApiKey } : process.env.OPENAI_API_KEY ? { llm_api_key: process.env.OPENAI_API_KEY } : {}),\n        }),\n      });\n      if (!res.ok) continue;\n      const data: any = await res.json();\n      const taskId: string = data.task_id;\n      if (!taskId) continue;\n      lastTaskId = taskId;\n\n      // Poll for task completion (max 60s per goal)\n      let done = false;\n      for (let p = 0; p < 12 && !done; p++) {\n        await new Promise((r) => setTimeout(r, 5000));\n        const poll = await fetch(`${apiUrl}/api/v1/tasks/${taskId}`, {\n          headers: { 'x-api-key': apiKey },\n        }).catch(() => null);\n        if (!poll?.ok) continue;\n        const pollData: any = await poll.json();\n        if (pollData.status === 'completed' || pollData.status === 'failed') {\n          done = true;\n          totalDurationMs += Date.now() - taskStart;\n          if (pollData.status === 'completed') {\n            if (pollData.output?.url) visitedUrls.push(pollData.output.url);\n            if (pollData.output?.screenshot_url) screenshotUrls.push(pollData.output.screenshot_url);\n          }\n\n          // Fetch step-level detail from Skyvern\n          try {\n            const stepsRes = await fetch(`${apiUrl}/api/v1/tasks/${taskId}/steps`, {\n              headers: { 'x-api-key': apiKey },\n            }).catch(() => null);\n            if (stepsRes?.ok) {\n              const stepsData: any = await stepsRes.json();\n              const stepsList = Array.isArray(stepsData) ? stepsData : (stepsData?.steps ?? []);\n              for (const s of stepsList) {\n                if (s.output?.screenshot_url) screenshotUrls.push(s.output.screenshot_url);\n                skyvernSteps.push({\n                  order: s.step_order ?? s.order ?? 0,\n                  action_type: s.action_type ?? s.action ?? 'unknown',\n                  element_description: s.output?.element_description,\n                  reasoning: s.output?.llm_response?.action_description ?? s.output?.reasoning,\n                  success: s.status === 'completed',\n                  screenshot_url: s.output?.screenshot_url,\n                  error: s.status === 'failed' ? (s.output?.errors?.[0] ?? 'Step failed') : undefined,\n                });\n              }\n            }\n          } catch { /* non-fatal */ }\n        }\n      }\n    } catch (err) {\n      console.warn(`[skyvern] Navigation goal failed: ${goal}`, err);\n    }\n  }\n\n  return {\n    screenshotUrls,\n    visitedUrls,\n    status: visitedUrls.length > 0 ? 'success' : screenshotUrls.length > 0 ? 'partial' : 'failed',\n    steps: skyvernSteps,\n    taskId: lastTaskId,\n    durationMs: totalDurationMs || undefined,\n    triggerReason,\n  };\n}\n\nexport async function skyvernFallback(task: SkyvernTask, tenantConfig?: SkyvernConfig): Promise<'success' | 'failed'> {\n  const apiUrl = tenantConfig?.apiUrl || process.env.SKYVERN_API_URL;\n  const apiKey = tenantConfig?.apiKey || process.env.SKYVERN_API_KEY;\n\n  if (!apiUrl || !apiKey) {\n    console.warn(\n      '[skyvern] Vision fallback disabled \u2014 set SKYVERN_API_URL + SKYVERN_API_KEY in .env to enable.',\n      '\\n[skyvern] Self-host: https://github.com/Skyvern-AI/skyvern'\n    );\n    return 'failed';\n  }\n\n  try {\n    const res = await fetch(`${apiUrl}/api/v1/tasks`, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },\n      body: JSON.stringify({\n        url: task.url,\n        navigation_goal: task.taskDescription,\n        ...(task.credentials && {\n          navigation_payload: {\n            username: task.credentials.username,\n            password: task.credentials.password,\n            ...(task.credentials.oneTimeCode && { otp: task.credentials.oneTimeCode }),\n          },\n        }),\n        ...(tenantConfig?.llmKey ? { llm_key: tenantConfig.llmKey } : process.env.SKYVERN_LLM_KEY ? { llm_key: process.env.SKYVERN_LLM_KEY } : {}),\n        ...(tenantConfig?.llmApiKey ? { llm_api_key: tenantConfig.llmApiKey } : process.env.OPENAI_API_KEY ? { llm_api_key: process.env.OPENAI_API_KEY } : {}),\n      }),\n    });\n\n    if (!res.ok) {\n      const body = await res.text().catch(() => '');\n      console.error(`[skyvern] Task creation failed: ${res.status}`, body);\n      return 'failed';\n    }\n\n    const data: any = await res.json();\n    console.log(`[skyvern] Task queued: ${data.task_id}. Poll GET /api/v1/tasks/${data.task_id} for completion.`);\n    // Full implementation: poll until status === \"completed\" | \"failed\".\n    // For Phase 1 the login already happened in the browser context Skyvern manages,\n    // so returning 'success' here means we can proceed in that browser session.\n    return 'success';\n  } catch (err) {\n    console.error('[skyvern] Error:', err);\n    return 'failed';\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/sqs-queue.d.ts

@@ -0,0 +1,13 @@
+export declare function sendJobToSqs(jobId: string): Promise<void>;
+/** Returns the approximate number of messages in the SQS DLQ. */
+export declare function getDlqStats(): Promise<{
+    approximateMessageCount: number;
+    dlqUrl: string | null;
+}>;
+/**
+ * Redrive up to `maxMessages` messages from the SQS DLQ back to the main queue.
+ * Each message is received from the DLQ, re-sent to the main queue, then deleted
+ * from the DLQ. Returns the number of messages successfully redriven.
+ */
+export declare function redriveFromDlq(maxMessages?: number): Promise<number>;
+export declare function startSqsWorker(): Promise<void>;

package/dist/sqs-queue.js

@@ -0,0 +1,115 @@
+import {
+  SQSClient,
+  SendMessageCommand,
+  ReceiveMessageCommand,
+  DeleteMessageCommand,
+  GetQueueAttributesCommand
+} from "@aws-sdk/client-sqs";
+const sqs = new SQSClient({ region: process.env.AWS_REGION ?? "us-east-1" });
+function getQueueUrl() {
+  const url = process.env.SQS_QUEUE_URL ?? process.env.SQS_CRAWL_QUEUE_URL;
+  if (!url) throw new Error("SQS_QUEUE_URL not configured");
+  return url;
+}
+function getDlqUrl() {
+  return process.env.SQS_DLQ_URL ?? null;
+}
+async function sendJobToSqs(jobId) {
+  await sqs.send(new SendMessageCommand({
+    QueueUrl: getQueueUrl(),
+    MessageBody: JSON.stringify({ jobId })
+  }));
+}
+async function getDlqStats() {
+  const dlqUrl = getDlqUrl();
+  if (!dlqUrl) return { approximateMessageCount: 0, dlqUrl: null };
+  try {
+    const { Attributes = {} } = await sqs.send(new GetQueueAttributesCommand({
+      QueueUrl: dlqUrl,
+      AttributeNames: ["ApproximateNumberOfMessages"]
+    }));
+    return {
+      approximateMessageCount: parseInt(Attributes.ApproximateNumberOfMessages ?? "0", 10),
+      dlqUrl
+    };
+  } catch (err) {
+    console.error("[sqs-dlq] getDlqStats error:", err.message);
+    return { approximateMessageCount: 0, dlqUrl };
+  }
+}
+async function redriveFromDlq(maxMessages = 10) {
+  const dlqUrl = getDlqUrl();
+  if (!dlqUrl) {
+    console.warn("[sqs-dlq] SQS_DLQ_URL not configured \u2014 cannot redrive");
+    return 0;
+  }
+  const mainUrl = getQueueUrl();
+  let totalRedriven = 0;
+  while (totalRedriven < maxMessages) {
+    const batch = Math.min(10, maxMessages - totalRedriven);
+    const { Messages = [] } = await sqs.send(new ReceiveMessageCommand({
+      QueueUrl: dlqUrl,
+      MaxNumberOfMessages: batch,
+      WaitTimeSeconds: 1
+    }));
+    if (Messages.length === 0) break;
+    for (const msg of Messages) {
+      try {
+        await sqs.send(new SendMessageCommand({
+          QueueUrl: mainUrl,
+          MessageBody: msg.Body
+        }));
+        await sqs.send(new DeleteMessageCommand({
+          QueueUrl: dlqUrl,
+          ReceiptHandle: msg.ReceiptHandle
+        }));
+        totalRedriven++;
+        console.log("[sqs-dlq] redriven message:", msg.MessageId);
+      } catch (err) {
+        console.error("[sqs-dlq] redrive error for message", msg.MessageId, ":", err.message);
+      }
+    }
+  }
+  return totalRedriven;
+}
+async function startSqsWorker() {
+  const queueUrl = getQueueUrl();
+  const { claimSpecificJob, dispatchClaimedJob } = await import("./job-queue.js");
+  console.log("[sqs-worker] starting, queue:", queueUrl);
+  while (true) {
+    try {
+      const { Messages = [] } = await sqs.send(new ReceiveMessageCommand({
+        QueueUrl: queueUrl,
+        WaitTimeSeconds: 20,
+        MaxNumberOfMessages: 2
+      }));
+      await Promise.all(Messages.map(async (msg) => {
+        let jobId = "?";
+        try {
+          const data = JSON.parse(msg.Body);
+          jobId = data.jobId;
+          const claimed = await claimSpecificJob(jobId);
+          if (claimed) {
+            await dispatchClaimedJob(claimed);
+          }
+          await sqs.send(new DeleteMessageCommand({
+            QueueUrl: queueUrl,
+            ReceiptHandle: msg.ReceiptHandle
+          }));
+        } catch (err) {
+          console.error(`[sqs-worker] job ${jobId} failed \u2014 leaving for SQS redrive:`, err.message);
+        }
+      }));
+    } catch (err) {
+      console.error("[sqs-worker] receive error:", err.message);
+      await new Promise((r) => setTimeout(r, 2e3));
+    }
+  }
+}
+export {
+  getDlqStats,
+  redriveFromDlq,
+  sendJobToSqs,
+  startSqsWorker
+};
+//# sourceMappingURL=sqs-queue.js.map

package/dist/sqs-queue.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/sqs-queue.ts"],
+  "sourcesContent": ["import {\n  SQSClient,\n  SendMessageCommand,\n  ReceiveMessageCommand,\n  DeleteMessageCommand,\n  GetQueueAttributesCommand,\n} from '@aws-sdk/client-sqs';\n\nconst sqs = new SQSClient({ region: process.env.AWS_REGION ?? 'us-east-1' });\n\nfunction getQueueUrl(): string {\n  const url = process.env.SQS_QUEUE_URL ?? process.env.SQS_CRAWL_QUEUE_URL;\n  if (!url) throw new Error('SQS_QUEUE_URL not configured');\n  return url;\n}\n\nfunction getDlqUrl(): string | null {\n  return process.env.SQS_DLQ_URL ?? null;\n}\n\nexport async function sendJobToSqs(jobId: string): Promise<void> {\n  await sqs.send(new SendMessageCommand({\n    QueueUrl: getQueueUrl(),\n    MessageBody: JSON.stringify({ jobId }),\n  }));\n}\n\n/** Returns the approximate number of messages in the SQS DLQ. */\nexport async function getDlqStats(): Promise<{ approximateMessageCount: number; dlqUrl: string | null }> {\n  const dlqUrl = getDlqUrl();\n  if (!dlqUrl) return { approximateMessageCount: 0, dlqUrl: null };\n  try {\n    const { Attributes = {} } = await sqs.send(new GetQueueAttributesCommand({\n      QueueUrl: dlqUrl,\n      AttributeNames: ['ApproximateNumberOfMessages'],\n    }));\n    return {\n      approximateMessageCount: parseInt(Attributes.ApproximateNumberOfMessages ?? '0', 10),\n      dlqUrl,\n    };\n  } catch (err: any) {\n    console.error('[sqs-dlq] getDlqStats error:', err.message);\n    return { approximateMessageCount: 0, dlqUrl };\n  }\n}\n\n/**\n * Redrive up to `maxMessages` messages from the SQS DLQ back to the main queue.\n * Each message is received from the DLQ, re-sent to the main queue, then deleted\n * from the DLQ. Returns the number of messages successfully redriven.\n */\nexport async function redriveFromDlq(maxMessages = 10): Promise<number> {\n  const dlqUrl = getDlqUrl();\n  if (!dlqUrl) {\n    console.warn('[sqs-dlq] SQS_DLQ_URL not configured \u2014 cannot redrive');\n    return 0;\n  }\n  const mainUrl = getQueueUrl();\n  let totalRedriven = 0;\n\n  while (totalRedriven < maxMessages) {\n    const batch = Math.min(10, maxMessages - totalRedriven);\n    const { Messages = [] } = await sqs.send(new ReceiveMessageCommand({\n      QueueUrl: dlqUrl,\n      MaxNumberOfMessages: batch,\n      WaitTimeSeconds: 1,\n    }));\n    if (Messages.length === 0) break;\n\n    for (const msg of Messages) {\n      try {\n        await sqs.send(new SendMessageCommand({\n          QueueUrl: mainUrl,\n          MessageBody: msg.Body!,\n        }));\n        await sqs.send(new DeleteMessageCommand({\n          QueueUrl: dlqUrl,\n          ReceiptHandle: msg.ReceiptHandle!,\n        }));\n        totalRedriven++;\n        console.log('[sqs-dlq] redriven message:', msg.MessageId);\n      } catch (err: any) {\n        console.error('[sqs-dlq] redrive error for message', msg.MessageId, ':', err.message);\n      }\n    }\n  }\n\n  return totalRedriven;\n}\n\nexport async function startSqsWorker(): Promise<void> {\n  const queueUrl = getQueueUrl();\n  const { claimSpecificJob, dispatchClaimedJob } = await import('./job-queue.js');\n  console.log('[sqs-worker] starting, queue:', queueUrl);\n\n  while (true) {\n    try {\n      const { Messages = [] } = await sqs.send(new ReceiveMessageCommand({\n        QueueUrl: queueUrl,\n        WaitTimeSeconds: 20,\n        MaxNumberOfMessages: 2,\n      }));\n\n      await Promise.all(Messages.map(async (msg) => {\n        let jobId = '?';\n        try {\n          const data = JSON.parse(msg.Body!);\n          jobId = data.jobId;\n          // Atomically move QUEUED \u2192 RUNNING; returns null if another worker beat us.\n          const claimed = await claimSpecificJob(jobId);\n          if (claimed) {\n            await dispatchClaimedJob(claimed);\n          }\n          // Delete whether we ran it or another worker did \u2014 message is handled either way.\n          await sqs.send(new DeleteMessageCommand({\n            QueueUrl: queueUrl,\n            ReceiptHandle: msg.ReceiptHandle!,\n          }));\n        } catch (err: any) {\n          console.error(`[sqs-worker] job ${jobId} failed \u2014 leaving for SQS redrive:`, err.message);\n          // Do NOT delete \u2014 SQS visibility timeout expires and DLQ handles retry.\n        }\n      }));\n    } catch (err: any) {\n      console.error('[sqs-worker] receive error:', err.message);\n      await new Promise((r) => setTimeout(r, 2000));\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/sso-token.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SSO token retrieval for Okta and Azure AD.
+ * Uses OAuth2 ROPC (Resource Owner Password Credentials) flow to get access tokens
+ * without browser-based login.
+ *
+ * Note: ROPC is deprecated in OAuth 2.1 but still supported by Okta and Azure AD
+ * for service accounts and automated testing scenarios.
+ */
+export type SsoProvider = 'okta' | 'azure_ad' | 'generic_oidc';
+export interface SsoConfig {
+    provider: SsoProvider;
+    /** Okta domain (e.g. 'mycompany.okta.com') or Azure tenant ID */
+    domain: string;
+    /** OAuth2 client ID */
+    clientId: string;
+    /** OAuth2 client secret (for client_credentials or confidential ROPC) */
+    clientSecret?: string;
+    /** Scopes to request (space-separated). Default: 'openid profile' */
+    scope?: string;
+}
+/**
+ * Get an access token using ROPC flow (username + password → token).
+ * Returns the access token string.
+ */
+export declare function getSsoToken(config: SsoConfig, username: string, password: string): Promise<string>;
+/**
+ * Get a client credentials token (no user — for service accounts).
+ */
+export declare function getSsoClientCredentialsToken(config: SsoConfig): Promise<string>;

package/dist/sso-token.js

@@ -0,0 +1,76 @@
+async function getSsoToken(config, username, password) {
+  let tokenUrl;
+  const params = {
+    grant_type: "password",
+    username,
+    password,
+    scope: config.scope ?? "openid profile",
+    client_id: config.clientId
+  };
+  if (config.clientSecret) {
+    params.client_secret = config.clientSecret;
+  }
+  switch (config.provider) {
+    case "okta":
+      tokenUrl = `https://${config.domain}/oauth2/v1/token`;
+      break;
+    case "azure_ad":
+      tokenUrl = `https://login.microsoftonline.com/${config.domain}/oauth2/v2.0/token`;
+      break;
+    case "generic_oidc":
+      tokenUrl = config.domain.startsWith("http") ? config.domain : `https://${config.domain}/oauth2/token`;
+      break;
+    default:
+      throw new Error(`Unknown SSO provider: ${config.provider}`);
+  }
+  const res = await fetch(tokenUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(params).toString()
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => res.statusText);
+    throw new Error(`SSO token request failed (${res.status}): ${body}`);
+  }
+  const data = await res.json();
+  if (data.error) throw new Error(`SSO error: ${data.error} \u2014 ${data.error_description}`);
+  if (!data.access_token) throw new Error("SSO response missing access_token");
+  return data.access_token;
+}
+async function getSsoClientCredentialsToken(config) {
+  if (!config.clientSecret) throw new Error("clientSecret required for client credentials flow");
+  let tokenUrl;
+  switch (config.provider) {
+    case "okta":
+      tokenUrl = `https://${config.domain}/oauth2/v1/token`;
+      break;
+    case "azure_ad":
+      tokenUrl = `https://login.microsoftonline.com/${config.domain}/oauth2/v2.0/token`;
+      break;
+    default:
+      tokenUrl = `https://${config.domain}/oauth2/token`;
+  }
+  const res = await fetch(tokenUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: config.clientId,
+      client_secret: config.clientSecret,
+      scope: config.scope ?? "openid profile"
+    }).toString()
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => res.statusText);
+    throw new Error(`SSO client credentials failed (${res.status}): ${body}`);
+  }
+  const data = await res.json();
+  if (data.error) throw new Error(`SSO error: ${data.error} \u2014 ${data.error_description}`);
+  if (!data.access_token) throw new Error("SSO response missing access_token");
+  return data.access_token;
+}
+export {
+  getSsoClientCredentialsToken,
+  getSsoToken
+};
+//# sourceMappingURL=sso-token.js.map

package/dist/sso-token.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/sso-token.ts"],
+  "sourcesContent": ["/**\n * SSO token retrieval for Okta and Azure AD.\n * Uses OAuth2 ROPC (Resource Owner Password Credentials) flow to get access tokens\n * without browser-based login.\n *\n * Note: ROPC is deprecated in OAuth 2.1 but still supported by Okta and Azure AD\n * for service accounts and automated testing scenarios.\n */\n\nexport type SsoProvider = 'okta' | 'azure_ad' | 'generic_oidc';\n\nexport interface SsoConfig {\n  provider: SsoProvider;\n  /** Okta domain (e.g. 'mycompany.okta.com') or Azure tenant ID */\n  domain: string;\n  /** OAuth2 client ID */\n  clientId: string;\n  /** OAuth2 client secret (for client_credentials or confidential ROPC) */\n  clientSecret?: string;\n  /** Scopes to request (space-separated). Default: 'openid profile' */\n  scope?: string;\n}\n\n/**\n * Get an access token using ROPC flow (username + password \u2192 token).\n * Returns the access token string.\n */\nexport async function getSsoToken(\n  config: SsoConfig,\n  username: string,\n  password: string\n): Promise<string> {\n  let tokenUrl: string;\n  const params: Record<string, string> = {\n    grant_type: 'password',\n    username,\n    password,\n    scope: config.scope ?? 'openid profile',\n    client_id: config.clientId,\n  };\n\n  if (config.clientSecret) {\n    params.client_secret = config.clientSecret;\n  }\n\n  switch (config.provider) {\n    case 'okta':\n      tokenUrl = `https://${config.domain}/oauth2/v1/token`;\n      break;\n    case 'azure_ad':\n      // domain here is the tenant ID (e.g. XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX or 'mycompany.onmicrosoft.com')\n      tokenUrl = `https://login.microsoftonline.com/${config.domain}/oauth2/v2.0/token`;\n      break;\n    case 'generic_oidc':\n      tokenUrl = config.domain.startsWith('http') ? config.domain : `https://${config.domain}/oauth2/token`;\n      break;\n    default:\n      throw new Error(`Unknown SSO provider: ${config.provider}`);\n  }\n\n  const res = await fetch(tokenUrl, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n    body: new URLSearchParams(params).toString(),\n  });\n\n  if (!res.ok) {\n    const body = await res.text().catch(() => res.statusText);\n    throw new Error(`SSO token request failed (${res.status}): ${body}`);\n  }\n\n  const data = await res.json() as { access_token?: string; error?: string; error_description?: string };\n  if (data.error) throw new Error(`SSO error: ${data.error} \u2014 ${data.error_description}`);\n  if (!data.access_token) throw new Error('SSO response missing access_token');\n\n  return data.access_token;\n}\n\n/**\n * Get a client credentials token (no user \u2014 for service accounts).\n */\nexport async function getSsoClientCredentialsToken(\n  config: SsoConfig\n): Promise<string> {\n  if (!config.clientSecret) throw new Error('clientSecret required for client credentials flow');\n\n  let tokenUrl: string;\n  switch (config.provider) {\n    case 'okta':\n      tokenUrl = `https://${config.domain}/oauth2/v1/token`;\n      break;\n    case 'azure_ad':\n      tokenUrl = `https://login.microsoftonline.com/${config.domain}/oauth2/v2.0/token`;\n      break;\n    default:\n      tokenUrl = `https://${config.domain}/oauth2/token`;\n  }\n\n  const res = await fetch(tokenUrl, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n    body: new URLSearchParams({\n      grant_type: 'client_credentials',\n      client_id: config.clientId,\n      client_secret: config.clientSecret,\n      scope: config.scope ?? 'openid profile',\n    }).toString(),\n  });\n\n  if (!res.ok) {\n    const body = await res.text().catch(() => res.statusText);\n    throw new Error(`SSO client credentials failed (${res.status}): ${body}`);\n  }\n\n  const data = await res.json() as { access_token?: string; error?: string; error_description?: string };\n  if (data.error) throw new Error(`SSO error: ${data.error} \u2014 ${data.error_description}`);\n  if (!data.access_token) throw new Error('SSO response missing access_token');\n\n  return data.access_token;\n}\n"],
+  "mappings": "AA2BA,eAAsB,YACpB,QACA,UACA,UACiB;AACjB,MAAI;AACJ,QAAM,SAAiC;AAAA,IACrC,YAAY;AAAA,IACZ;AAAA,IACA;AAAA,IACA,OAAO,OAAO,SAAS;AAAA,IACvB,WAAW,OAAO;AAAA,EACpB;AAEA,MAAI,OAAO,cAAc;AACvB,WAAO,gBAAgB,OAAO;AAAA,EAChC;AAEA,UAAQ,OAAO,UAAU;AAAA,IACvB,KAAK;AACH,iBAAW,WAAW,OAAO,MAAM;AACnC;AAAA,IACF,KAAK;AAEH,iBAAW,qCAAqC,OAAO,MAAM;AAC7D;AAAA,IACF,KAAK;AACH,iBAAW,OAAO,OAAO,WAAW,MAAM,IAAI,OAAO,SAAS,WAAW,OAAO,MAAM;AACtF;AAAA,IACF;AACE,YAAM,IAAI,MAAM,yBAAyB,OAAO,QAAQ,EAAE;AAAA,EAC9D;AAEA,QAAM,MAAM,MAAM,MAAM,UAAU;AAAA,IAChC,QAAQ;AAAA,IACR,SAAS,EAAE,gBAAgB,oCAAoC;AAAA,IAC/D,MAAM,IAAI,gBAAgB,MAAM,EAAE,SAAS;AAAA,EAC7C,CAAC;AAED,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,UAAU;AACxD,UAAM,IAAI,MAAM,6BAA6B,IAAI,MAAM,MAAM,IAAI,EAAE;AAAA,EACrE;AAEA,QAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,MAAI,KAAK,MAAO,OAAM,IAAI,MAAM,cAAc,KAAK,KAAK,WAAM,KAAK,iBAAiB,EAAE;AACtF,MAAI,CAAC,KAAK,aAAc,OAAM,IAAI,MAAM,mCAAmC;AAE3E,SAAO,KAAK;AACd;AAKA,eAAsB,6BACpB,QACiB;AACjB,MAAI,CAAC,OAAO,aAAc,OAAM,IAAI,MAAM,mDAAmD;AAE7F,MAAI;AACJ,UAAQ,OAAO,UAAU;AAAA,IACvB,KAAK;AACH,iBAAW,WAAW,OAAO,MAAM;AACnC;AAAA,IACF,KAAK;AACH,iBAAW,qCAAqC,OAAO,MAAM;AAC7D;AAAA,IACF;AACE,iBAAW,WAAW,OAAO,MAAM;AAAA,EACvC;AAEA,QAAM,MAAM,MAAM,MAAM,UAAU;AAAA,IAChC,QAAQ;AAAA,IACR,SAAS,EAAE,gBAAgB,oCAAoC;AAAA,IAC/D,MAAM,IAAI,gBAAgB;AAAA,MACxB,YAAY;AAAA,MACZ,WAAW,OAAO;AAAA,MAClB,eAAe,OAAO;AAAA,MACtB,OAAO,OAAO,SAAS;AAAA,IACzB,CAAC,EAAE,SAAS;AAAA,EACd,CAAC;AAED,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,UAAU;AACxD,UAAM,IAAI,MAAM,kCAAkC,IAAI,MAAM,MAAM,IAAI,EAAE;AAAA,EAC1E;AAEA,QAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,MAAI,KAAK,MAAO,OAAM,IAAI,MAAM,cAAc,KAAK,KAAK,WAAM,KAAK,iBAAiB,EAAE;AACtF,MAAI,CAAC,KAAK,aAAc,OAAM,IAAI,MAAM,mCAAmC;AAE3E,SAAO,KAAK;AACd;",
+  "names": []
+}

package/dist/state-graph.d.ts

@@ -0,0 +1,59 @@
+import type { Page } from 'playwright';
+export declare function simHash32(text: string): number;
+export declare function hammingDistance32(a: number, b: number): number;
+export declare function normalizeUrl(raw: string): string;
+export declare function computeStateId(normalizedUrl: string, hash: number): string;
+export interface UIStateNode {
+    id: string;
+    url: string;
+    normalizedUrl: string;
+    title: string;
+    interactiveElementCount: number;
+    domFingerprint: string;
+    simHashValue: number;
+    visitedAt: string;
+}
+export interface StateTransition {
+    fromId: string;
+    toId: string;
+    action: string;
+    label: string;
+    triggeredAt: string;
+}
+export interface CoverageReport {
+    totalStates: number;
+    totalTransitions: number;
+    uniqueUrls: number;
+    interactiveElementsTotal: number;
+    estimatedCoveragePercent: number;
+}
+export declare function fingerprintPage(page: Page, visitedAt: string): Promise<{
+    fingerprint: string;
+    visibleText: string;
+    interactiveCount: number;
+    simHashValue: number;
+}>;
+export declare class ScreenTransitionGraph {
+    private states;
+    private transitions;
+    /** Maps simHash value → array of state ids with that hash (for near-dup lookup) */
+    private hashIndex;
+    addState(node: UIStateNode): {
+        added: boolean;
+        duplicateOf?: string;
+    };
+    addTransition(fromId: string, toId: string, action: string, label: string, triggeredAt: string): void;
+    isDuplicate(url: string, visibleText: string, threshold?: number): boolean;
+    getCoverageReport(): CoverageReport;
+    toJSON(): {
+        states: UIStateNode[];
+        transitions: StateTransition[];
+    };
+    static fromJSON(data: {
+        states: UIStateNode[];
+        transitions: StateTransition[];
+    }): ScreenTransitionGraph;
+    getState(id: string): UIStateNode | undefined;
+    getAllStates(): UIStateNode[];
+    getTransitionsFrom(id: string): StateTransition[];
+}