salesprompter-cli 0.1.65 → 0.1.67

package/README.md

@@ -73,6 +73,11 @@ salesprompter contacts:resolve-emails --in ./contacts.tsv --out-dir ./email-run
 salesprompter leads:collect \
   --linkedin-url "$SALES_NAV_PEOPLE_URL"
 
+# For large discovery runs, store the leads now and enrich selected imports later
+salesprompter leads:collect \
+  --linkedin-url "$SALES_NAV_PEOPLE_URL" \
+  --defer-email-enrichment
+
 # Enrich one or more stored imports: Sales Navigator company -> official domain -> Hunter email
 # This updates workspace data only. It does not create or start outreach.
 # Stale ids and raw legal-name misses use conservative exact-name recovery.
@@ -120,6 +125,19 @@ salesprompter packs:list
 salesprompter --help
 ```
 
+Collect an exact signed-in LinkedIn product-search order locally, without uploading it:
+
+```bash
+salesprompter products:collect \
+  --query-url "$LINKEDIN_PRODUCTS_URL" \
+  --checkpoint ./data/products.checkpoint.json \
+  --raw-jsonl ./data/products.raw.jsonl \
+  --out ./data/products.complete.json \
+  --relay-port 43117
+```
+
+Use a signed-in in-app-browser worker with the loopback `GET /task` and `POST /page` protocol. Interrupted, bounded, challenged, or rate-limited runs remain checkpointed and do not create the complete artifact.
+
 Download stored workspace leads without starting a new Sales Navigator scrape:
 
 ```bash

package/dist/cli.js

@@ -28,6 +28,7 @@ import { buildHistoricalVendorIcp, buildVendorIcp } from "./icp-templates.js";
 import { InstantlySyncProvider } from "./instantly.js";
 import { backfillLinkedInCompanies } from "./linkedin-companies.js";
 import { parseLinkedInCompanyPage } from "./linkedin-companies.js";
+import { collectLinkedInProductsViaBrowserRelay } from "./linkedin-product-search.js";
 import { crawlLinkedInProductCategory } from "./linkedin-products.js";
 import { claimLinkedInSessionCookieForCli, claimValidatedSalesNavigatorSessionCookieForCli, createLinkedInSessionSupabaseClient, recordLinkedInSessionCookieAudit, resolveConfiguredEnvValue } from "./linkedin-session.js";
 import { buildLeadlistsFunnelQueries } from "./leadlists-funnel.js";
@@ -296,6 +297,23 @@ const SalesNavigatorLocalImportResponseSchema = z.object({
     })
         .nullable()
         .optional(),
+    emailEnrichment: z
+        .object({
+        scheduled: z.boolean(),
+        deferred: z.boolean().optional(),
+        provider: z.string().min(1).optional(),
+        fallbackProvider: z.string().min(1).optional(),
+    })
+        .optional(),
+    enrichmentDeferred: z.boolean().optional(),
+    outreachStarted: z.literal(false).optional(),
+});
+const SalesNavigatorLocalImportCapabilitiesResponseSchema = z.object({
+    status: z.literal("ok"),
+    capabilities: z.object({
+        deferredEmailEnrichment: z.literal(true),
+    }),
+    outreachStarted: z.literal(false),
 });
 const PhantombusterContainersSyncResponseSchema = z.object({
     status: z.literal("ok"),
@@ -581,7 +599,7 @@ const cliPacks = [
         slug: "research",
         title: "Research",
         summary: "Scrape markets and enrich companies before outreach.",
-        commands: ["market:scrape", "companies:enrich"],
+        commands: ["products:collect", "market:scrape", "companies:enrich"],
         installStatus: "included"
     },
     {
@@ -631,6 +649,7 @@ const helpAliasByCommandName = new Map([
     ["linkedin-companies:backfill", "companies:enrich"],
     ["linkedin-companies:scrape-local", "companies:scrape-linkedin"],
     ["dealroom-companies:scrape-local", "companies:scrape-dealroom"],
+    ["linkedin-products:collect", "products:collect"],
     ["linkedin-products:scrape", "market:scrape"],
     ["salesnav:from-product-category", "leads:discover"],
     ["salesnav:people:collect", "leads:collect"],
@@ -681,6 +700,7 @@ const helpVisibleCommandNames = new Set([
     "linkedin-companies:backfill",
     "linkedin-companies:scrape-local",
     "dealroom-companies:scrape-local",
+    "linkedin-products:collect",
     "linkedin-products:scrape",
     "salesnav:from-product-category",
     "salesnav:people:collect",
@@ -9275,6 +9295,9 @@ async function importLocalSalesNavigatorPeopleViaApp(session, payload) {
             totalResults: payload.totalResults,
             fetchedPages: payload.fetchedPages,
             people: payload.people,
+            ...(payload.startEmailEnrichment === false
+                ? { startEmailEnrichment: false }
+                : {}),
             rawPayload: {
                 ...payload.rawPayload,
                 clientId: workspaceClientId ?? undefined,
@@ -9305,6 +9328,20 @@ async function importLocalSalesNavigatorPeopleViaApp(session, payload) {
     }, SalesNavigatorLocalImportResponseSchema);
     return value;
 }
+async function requireDeferredEmailEnrichmentCapability(session) {
+    try {
+        const result = await fetchCliJson(session, (currentSession) => fetch(`${currentSession.apiBaseUrl}/api/cli/salesnav/local-import`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${currentSession.accessToken}`,
+            },
+        }), SalesNavigatorLocalImportCapabilitiesResponseSchema);
+        return result.session;
+    }
+    catch {
+        throw new Error("This Salesprompter workspace cannot safely defer email enrichment yet. Update the app before collecting leads with --defer-email-enrichment.");
+    }
+}
 const SALESPROMPTER_SUPABASE_TABLES = {
     accountSearchRuns: "salesprompter_linkedin_sales_nav_account_search_runs",
     accountSearchSlices: "salesprompter_linkedin_sales_nav_account_search_slices",
@@ -13813,6 +13850,7 @@ async function runSalesNavigatorPeopleCollectCommand(options) {
             .max(accessibleResultLimit)
             .parse(options.maxResults);
     const complete = Boolean(options.complete || options.maxResults == null);
+    const emailEnrichmentDeferred = Boolean(options.deferEmailEnrichment);
     const checkpointPath = complete
         ? options.checkpoint
             ? path.resolve(options.checkpoint)
@@ -13827,13 +13865,18 @@ async function runSalesNavigatorPeopleCollectCommand(options) {
             accessibleResultLimit,
             complete,
             resumable: complete,
+            emailEnrichmentDeferred,
+            outreachStarted: false,
             destination: "/leads/cli-imports"
         };
         if (options.out)
             await writeJsonFile(options.out, payload);
         return payload;
     }
-    const session = await requireAuthSession();
+    let session = await requireAuthSession();
+    if (emailEnrichmentDeferred) {
+        session = await requireDeferredEmailEnrichmentCapability(session);
+    }
     const pageDelayMinMs = z.coerce.number().int().min(0).parse(options.pageDelayMinMs);
     const pageDelayMaxMs = z.coerce.number().int().min(pageDelayMinMs).parse(options.pageDelayMaxMs);
     const browserRelayPort = options.browserRelayPort == null
@@ -13899,6 +13942,9 @@ async function runSalesNavigatorPeopleCollectCommand(options) {
         slicePreset: adaptiveCollection
             ? "local-salesnav-people-adaptive"
             : "local-salesnav-people",
+        ...(emailEnrichmentDeferred
+            ? { startEmailEnrichment: false }
+            : {}),
         rawPayload: adaptiveCollection
             ? {
                 collectionMode: adaptiveCollection.collectionMode,
@@ -13914,6 +13960,13 @@ async function runSalesNavigatorPeopleCollectCommand(options) {
                 accessibleResultLimit,
             },
     });
+    if (emailEnrichmentDeferred &&
+        !(imported.enrichmentDeferred === true &&
+            imported.emailEnrichment?.deferred === true &&
+            imported.emailEnrichment.scheduled === false &&
+            imported.outreachStarted === false)) {
+        throw new Error(`Import ${imported.runId} was stored, but the workspace did not confirm that email enrichment was deferred. Do not repeat the collection until that run's enrichment state is verified.`);
+    }
     const payload = {
         status: "ok",
         dryRun: false,
@@ -13942,6 +13995,10 @@ async function runSalesNavigatorPeopleCollectCommand(options) {
         runId: imported.runId,
         imported: imported.imported,
         upserted: imported.upserted,
+        emailEnrichmentDeferred: imported.enrichmentDeferred ??
+            imported.emailEnrichment?.deferred ??
+            false,
+        outreachStarted: imported.outreachStarted ?? false,
         workspaceUrl: `${session.apiBaseUrl}/leads/cli-imports?runId=` +
             encodeURIComponent(imported.runId)
     };
@@ -14807,6 +14864,7 @@ program
     .option("--max-results <number>", "Bounded collection size; defaults to exhaustive collection with a 2500-person window")
     .option("--complete", "Split oversized searches by company headcount and deduplicate the complete result", false)
     .option("--checkpoint <path>", "Optional resume checkpoint; exhaustive runs use a per-query checkpoint by default")
+    .option("--defer-email-enrichment", "Store leads without starting email enrichment", false)
     .option("--curl-file <path>", "Optional copied Sales Navigator Lead Search curl request")
     .option("--browser-relay-port <number>", "Use the signed-in browser through a loopback relay")
     .option("--page-size <number>", "Direct Sales Navigator page size", "100")
@@ -15128,6 +15186,43 @@ program
         profile,
     });
 });
+program
+    .command("linkedin-products:collect")
+    .alias("products:collect")
+    .description("Collect an exact LinkedIn product-search order locally through a loopback browser relay.")
+    .requiredOption("--query-url <url>", "Exact LinkedIn /search/results/products/ query URL")
+    .requiredOption("--checkpoint <path>", "Private resumable checkpoint JSON path")
+    .requiredOption("--raw-jsonl <path>", "Private append-only normalized page evidence path")
+    .requiredOption("--out <path>", "Complete public-fields-only ranked artifact path")
+    .requiredOption("--relay-port <number>", "Loopback relay port for GET /task and POST /page")
+    .option("--max-pages <number>", "Optional highest page number to accept in this run")
+    .option("--max-requests <number>", "Optional number of unique browser tasks to issue in this run")
+    .action(async (options) => {
+    const relayPort = z.coerce.number().int().min(1).max(65_535).parse(options.relayPort);
+    const maxPages = options.maxPages === undefined
+        ? undefined
+        : z.coerce.number().int().min(1).max(100_000).parse(options.maxPages);
+    const maxRequests = options.maxRequests === undefined
+        ? undefined
+        : z.coerce.number().int().min(1).max(100_000).parse(options.maxRequests);
+    const idleTimeoutMs = process.env.SALESPROMPTER_LINKEDIN_PRODUCTS_RELAY_IDLE_TIMEOUT_MS
+        ? z.coerce.number().int().min(100).max(86_400_000).parse(process.env.SALESPROMPTER_LINKEDIN_PRODUCTS_RELAY_IDLE_TIMEOUT_MS)
+        : undefined;
+    const result = await collectLinkedInProductsViaBrowserRelay({
+        queryUrl: String(options.queryUrl),
+        checkpointPath: path.resolve(String(options.checkpoint)),
+        rawJsonlPath: path.resolve(String(options.rawJsonl)),
+        outPath: path.resolve(String(options.out)),
+        relayPort,
+        maxPages,
+        maxRequests,
+        idleTimeoutMs,
+        onListening: ({ taskUrl, pageUrl }) => {
+            writeProgress(`LinkedIn product relay ready: GET ${taskUrl} and POST ${pageUrl}`);
+        }
+    });
+    printOutput(result);
+});
 program
     .command("linkedin-products:scrape")
     .alias("market:scrape")

package/dist/linkedin-product-search.js

@@ -0,0 +1,1081 @@
+import { createHash, randomUUID } from "node:crypto";
+import { access, appendFile, chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import { z } from "zod";
+const CHECKPOINT_SCHEMA_VERSION = 1;
+const ARTIFACT_SCHEMA_VERSION = 1;
+const MAX_RELAY_BODY_BYTES = 5 * 1024 * 1024;
+const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+const nonEmptyText = (max) => z.string().trim().min(1).max(max);
+const optionalPublicUrl = z.string().trim().url().max(4_096).optional();
+export const visibleLinkedInProductCardSchema = z
+    .object({
+    identity: z.string().trim().min(1).max(256).optional(),
+    name: nonEmptyText(500),
+    linkedinUrl: nonEmptyText(4_096),
+    imageUrl: optionalPublicUrl,
+    vendor: nonEmptyText(500).optional(),
+    category: nonEmptyText(500).optional(),
+    description: nonEmptyText(10_000).optional()
+})
+    .strict();
+const pageSuccessSchema = z
+    .object({
+    pageNumber: z.number().int().min(1),
+    currentUrl: nonEmptyText(8_192),
+    reportedTotal: z.number().int().min(0).nullable().optional(),
+    hasNext: z.boolean(),
+    items: z.array(visibleLinkedInProductCardSchema).max(1_000)
+})
+    .strict();
+const terminalErrorSchema = z
+    .object({
+    pageNumber: z.number().int().min(1),
+    currentUrl: nonEmptyText(8_192),
+    error: z
+        .object({
+        code: z.enum([
+            "auth_required",
+            "challenge",
+            "rate_limited",
+            "interrupted",
+            "unexpected_page"
+        ]),
+        message: z.string().trim().max(1_000).optional()
+    })
+        .strict()
+})
+    .strict();
+export const linkedInProductPageSubmissionSchema = z.union([pageSuccessSchema, terminalErrorSchema]);
+const rawVisibleProductCardSchema = visibleLinkedInProductCardSchema
+    .extend({ linkedinSlug: nonEmptyText(500) })
+    .strict();
+const rawPageEvidenceSchema = z
+    .object({
+    type: z.literal("page"),
+    queryHash: z.string().regex(/^[a-f0-9]{64}$/),
+    pageNumber: z.number().int().min(1),
+    currentUrl: nonEmptyText(8_192),
+    reportedTotal: z.number().int().min(0).nullable(),
+    hasNext: z.boolean(),
+    items: z.array(rawVisibleProductCardSchema).max(1_000),
+    visibleItemCount: z.number().int().min(0),
+    newProductCount: z.number().int().min(0),
+    duplicateCount: z.number().int().min(0),
+    receivedAt: nonEmptyText(100)
+})
+    .strict();
+const rawTerminalEvidenceSchema = z
+    .object({
+    type: z.literal("terminal_error"),
+    queryHash: z.string().regex(/^[a-f0-9]{64}$/),
+    pageNumber: z.number().int().min(1),
+    currentUrl: nonEmptyText(8_192),
+    error: z.object({ code: terminalErrorSchema.shape.error.shape.code }).strict(),
+    receivedAt: nonEmptyText(100)
+})
+    .strict();
+const rawEvidenceRecordSchema = z.union([rawPageEvidenceSchema, rawTerminalEvidenceSchema]);
+export class LinkedInProductCollectorInvariantError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "LinkedInProductCollectorInvariantError";
+    }
+}
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function cleanText(value) {
+    const cleaned = value?.replace(/\s+/g, " ").trim();
+    return cleaned || undefined;
+}
+function canonicalizePublicUrl(value) {
+    if (!value)
+        return undefined;
+    const parsed = new URL(value);
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new LinkedInProductCollectorInvariantError("invalid_public_url", `Unsupported public URL: ${value}`);
+    }
+    parsed.username = "";
+    parsed.password = "";
+    parsed.hash = "";
+    return parsed.toString();
+}
+export function normalizeLinkedInProductSearchUrl(input) {
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("invalid_query_url", "The query URL is not a valid URL.");
+    }
+    if (parsed.protocol !== "https:" ||
+        parsed.port !== "" ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        !["linkedin.com", "www.linkedin.com"].includes(parsed.hostname.toLowerCase())) {
+        throw new LinkedInProductCollectorInvariantError("invalid_query_url", "The query URL must use https://www.linkedin.com.");
+    }
+    if (parsed.pathname !== "/search/results/products" && parsed.pathname !== "/search/results/products/") {
+        throw new LinkedInProductCollectorInvariantError("invalid_query_url", "The query URL must point to /search/results/products/.");
+    }
+    const suppliedPages = parsed.searchParams.getAll("page");
+    const suppliedPage = suppliedPages[0];
+    if (suppliedPages.length > 1 || (suppliedPage && suppliedPage !== "1")) {
+        throw new LinkedInProductCollectorInvariantError("invalid_query_url", "An exhaustive collection must begin on page 1; remove the page parameter.");
+    }
+    parsed.protocol = "https:";
+    parsed.hostname = "www.linkedin.com";
+    parsed.port = "";
+    parsed.username = "";
+    parsed.password = "";
+    parsed.pathname = "/search/results/products/";
+    parsed.hash = "";
+    parsed.searchParams.delete("page");
+    return parsed.toString();
+}
+export function buildLinkedInProductSearchPageUrl(queryUrl, pageNumber) {
+    if (!Number.isInteger(pageNumber) || pageNumber < 1) {
+        throw new LinkedInProductCollectorInvariantError("invalid_page", "Page numbers must be positive integers.");
+    }
+    const parsed = new URL(normalizeLinkedInProductSearchUrl(queryUrl));
+    if (pageNumber > 1)
+        parsed.searchParams.set("page", String(pageNumber));
+    return parsed.toString();
+}
+function assertExpectedLinkedInSearchPage(currentUrl, queryUrl, pageNumber) {
+    let actual;
+    try {
+        actual = new URL(currentUrl);
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", "The browser reported an invalid page URL.");
+    }
+    const source = new URL(normalizeLinkedInProductSearchUrl(queryUrl));
+    if (actual.protocol !== "https:" ||
+        actual.port !== "" ||
+        actual.username !== "" ||
+        actual.password !== "" ||
+        !["linkedin.com", "www.linkedin.com"].includes(actual.hostname.toLowerCase()) ||
+        (actual.pathname !== "/search/results/products" && actual.pathname !== "/search/results/products/")) {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", "The browser is not on the expected LinkedIn product-search page.");
+    }
+    for (const key of new Set(source.searchParams.keys())) {
+        const expectedValues = source.searchParams.getAll(key);
+        const actualValues = actual.searchParams.getAll(key);
+        if (expectedValues.length !== actualValues.length || expectedValues.some((value, index) => value !== actualValues[index])) {
+            throw new LinkedInProductCollectorInvariantError("unexpected_page", `The browser page changed the original ${key} query filter.`);
+        }
+    }
+    const sourceKeys = new Set(source.searchParams.keys());
+    for (const key of new Set(actual.searchParams.keys())) {
+        if (!sourceKeys.has(key) && key !== "page" && key !== "spellCorrectionEnabled") {
+            throw new LinkedInProductCollectorInvariantError("unexpected_page", `The browser page added the unapproved ${key} query parameter.`);
+        }
+    }
+    const spellCorrectionValues = actual.searchParams.getAll("spellCorrectionEnabled");
+    if (spellCorrectionValues.length > 1 ||
+        spellCorrectionValues.some((value) => value !== "true" && value !== "false")) {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", "The browser reported an invalid spellCorrectionEnabled parameter.");
+    }
+    const actualPages = actual.searchParams.getAll("page");
+    const actualPage = actualPages[0] ?? null;
+    if (actualPages.length > 1) {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", "The browser reported multiple page numbers.");
+    }
+    if (pageNumber === 1) {
+        if (actualPage && actualPage !== "1") {
+            throw new LinkedInProductCollectorInvariantError("unexpected_page", "The browser reported the wrong page number.");
+        }
+    }
+    else if (actualPage !== String(pageNumber)) {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", "The browser reported the wrong page number.");
+    }
+    return buildLinkedInProductSearchPageUrl(queryUrl, pageNumber);
+}
+export function canonicalizeLinkedInProductUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value, "https://www.linkedin.com");
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("invalid_product_url", `Invalid LinkedIn product URL: ${value}`);
+    }
+    if (parsed.protocol !== "https:" ||
+        parsed.port !== "" ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        !["linkedin.com", "www.linkedin.com"].includes(parsed.hostname.toLowerCase())) {
+        throw new LinkedInProductCollectorInvariantError("invalid_product_url", `Product URL is outside LinkedIn: ${value}`);
+    }
+    const match = parsed.pathname.match(/^\/products\/([^/]+)\/?$/i);
+    if (!match?.[1]) {
+        throw new LinkedInProductCollectorInvariantError("invalid_product_url", `Product URL must match /products/<slug>/: ${value}`);
+    }
+    let decodedSlug;
+    try {
+        decodedSlug = decodeURIComponent(match[1]).trim().normalize("NFC").toLowerCase();
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("invalid_product_url", `Invalid encoded product slug: ${value}`);
+    }
+    if (!decodedSlug || /[\u0000-\u001f\u007f/\\]/.test(decodedSlug)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_product_url", `Invalid LinkedIn product slug: ${match[1]}`);
+    }
+    const slug = encodeURIComponent(decodedSlug)
+        .replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).padStart(2, "0")}`)
+        .toLowerCase();
+    if (slug.length > 720 || !/^(?:[a-z0-9._~-]|%[0-9a-f]{2})+$/.test(slug)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_product_url", `Invalid LinkedIn product slug: ${slug}`);
+    }
+    return {
+        linkedinUrl: `https://www.linkedin.com/products/${slug}`,
+        linkedinSlug: slug
+    };
+}
+function normalizeIdentity(value) {
+    const identity = cleanText(value);
+    if (!identity)
+        return undefined;
+    if (!/^[A-Za-z0-9:._-]+$/.test(identity)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_identity", "Product identity contains unsupported characters.");
+    }
+    return identity;
+}
+function normalizeVisibleProductCard(card, rank) {
+    const { linkedinUrl, linkedinSlug } = canonicalizeLinkedInProductUrl(card.linkedinUrl);
+    const name = cleanText(card.name);
+    if (!name) {
+        throw new LinkedInProductCollectorInvariantError("invalid_product", "A visible product card is missing its name.");
+    }
+    const imageUrl = canonicalizePublicUrl(card.imageUrl);
+    const vendor = cleanText(card.vendor);
+    const category = cleanText(card.category);
+    const description = cleanText(card.description);
+    const identity = normalizeIdentity(card.identity);
+    return {
+        rank,
+        name,
+        linkedinUrl,
+        linkedinSlug,
+        ...(imageUrl ? { imageUrl } : {}),
+        ...(vendor ? { vendor } : {}),
+        ...(category ? { category } : {}),
+        ...(description ? { description } : {}),
+        ...(identity ? { identity } : {})
+    };
+}
+export function createLinkedInProductCollectorCheckpoint(queryUrl, now = new Date()) {
+    const normalizedQueryUrl = normalizeLinkedInProductSearchUrl(queryUrl);
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: CHECKPOINT_SCHEMA_VERSION,
+        queryUrl: normalizedQueryUrl,
+        queryHash: sha256(normalizedQueryUrl),
+        startedAt: timestamp,
+        updatedAt: timestamp,
+        status: "collecting",
+        nextPageNumber: 1,
+        pagesAccepted: 0,
+        tasksIssued: 0,
+        approximateReportedTotal: null,
+        products: []
+    };
+}
+export function applyLinkedInProductSearchPage(checkpoint, submission, now = new Date()) {
+    if (checkpoint.status !== "collecting") {
+        throw new LinkedInProductCollectorInvariantError("checkpoint_closed", "The checkpoint is not collecting.");
+    }
+    if (submission.pageNumber !== checkpoint.nextPageNumber) {
+        throw new LinkedInProductCollectorInvariantError("out_of_order_page", `Expected page ${checkpoint.nextPageNumber}, received page ${submission.pageNumber}.`);
+    }
+    const currentUrl = assertExpectedLinkedInSearchPage(submission.currentUrl, checkpoint.queryUrl, submission.pageNumber);
+    if (submission.hasNext && submission.items.length === 0) {
+        throw new LinkedInProductCollectorInvariantError("empty_page_with_next", "A page that claims to have a next page must contain at least one visible product card.");
+    }
+    const products = checkpoint.products.map((product) => ({ ...product }));
+    const byUrl = new Map(products.map((product) => [product.linkedinUrl, product]));
+    const byIdentity = new Map();
+    for (const product of products) {
+        if (product.identity)
+            byIdentity.set(product.identity, product);
+    }
+    let duplicateCount = 0;
+    let newProductCount = 0;
+    for (const input of submission.items) {
+        const candidate = normalizeVisibleProductCard(input, products.length + 1);
+        const existingByUrl = byUrl.get(candidate.linkedinUrl);
+        const existingByIdentity = candidate.identity ? byIdentity.get(candidate.identity) : undefined;
+        if (existingByIdentity && existingByIdentity.linkedinUrl !== candidate.linkedinUrl) {
+            throw new LinkedInProductCollectorInvariantError("identity_drift", `Product identity ${candidate.identity} moved to a different canonical URL.`);
+        }
+        if (existingByUrl) {
+            if (candidate.identity && existingByUrl.identity && candidate.identity !== existingByUrl.identity) {
+                throw new LinkedInProductCollectorInvariantError("identity_drift", `Canonical URL ${candidate.linkedinUrl} changed product identity.`);
+            }
+            if (existingByUrl.name !== candidate.name) {
+                throw new LinkedInProductCollectorInvariantError("identity_drift", `Canonical URL ${candidate.linkedinUrl} changed product name.`);
+            }
+            if (!existingByUrl.identity && candidate.identity) {
+                existingByUrl.identity = candidate.identity;
+                byIdentity.set(candidate.identity, existingByUrl);
+            }
+            duplicateCount += 1;
+            continue;
+        }
+        products.push(candidate);
+        byUrl.set(candidate.linkedinUrl, candidate);
+        if (candidate.identity)
+            byIdentity.set(candidate.identity, candidate);
+        newProductCount += 1;
+    }
+    products.forEach((product, index) => {
+        if (product.rank !== index + 1) {
+            throw new LinkedInProductCollectorInvariantError("rank_drift", "Checkpoint ranks are not contiguous.");
+        }
+    });
+    const capturedAt = now.toISOString();
+    const reportedTotal = submission.reportedTotal ?? checkpoint.approximateReportedTotal;
+    const terminalPage = submission.hasNext
+        ? undefined
+        : {
+            pageNumber: submission.pageNumber,
+            currentUrl,
+            reportedTotal: submission.reportedTotal ?? null,
+            hasNext: false,
+            visibleItemCount: submission.items.length,
+            newProductCount,
+            capturedAt
+        };
+    const nextCheckpoint = {
+        ...checkpoint,
+        updatedAt: capturedAt,
+        status: submission.hasNext ? "collecting" : "complete",
+        nextPageNumber: submission.hasNext ? submission.pageNumber + 1 : submission.pageNumber,
+        pagesAccepted: checkpoint.pagesAccepted + 1,
+        tasksIssued: Math.max(checkpoint.tasksIssued, checkpoint.pagesAccepted + 1),
+        approximateReportedTotal: reportedTotal ?? null,
+        products,
+        ...(terminalPage ? { terminalPage, completedAt: capturedAt } : {}),
+        lastStop: undefined
+    };
+    if (terminalPage)
+        nextCheckpoint.orderChecksum = computeLinkedInProductOrderChecksum(products);
+    return { checkpoint: nextCheckpoint, newProductCount, duplicateCount };
+}
+export function computeLinkedInProductOrderChecksum(products) {
+    const manifest = products.map((product) => `${product.rank}\t${product.linkedinUrl}`).join("\n");
+    return sha256(manifest);
+}
+export function buildLinkedInProductCollectionArtifact(checkpoint) {
+    assertValidCheckpoint(checkpoint);
+    if (checkpoint.status !== "complete" || !checkpoint.terminalPage || !checkpoint.completedAt) {
+        throw new LinkedInProductCollectorInvariantError("incomplete_checkpoint", "A complete artifact requires natural terminal-page evidence.");
+    }
+    const products = checkpoint.products.map((stored) => {
+        const canonical = canonicalizeLinkedInProductUrl(stored.linkedinUrl);
+        if (canonical.linkedinSlug !== stored.linkedinSlug) {
+            throw new LinkedInProductCollectorInvariantError("canonical_url_drift", "Checkpoint product URL and slug disagree.");
+        }
+        const name = cleanText(stored.name);
+        if (!name)
+            throw new LinkedInProductCollectorInvariantError("invalid_product", "Checkpoint product name is empty.");
+        const imageUrl = canonicalizePublicUrl(stored.imageUrl);
+        const vendor = cleanText(stored.vendor);
+        const category = cleanText(stored.category);
+        const description = cleanText(stored.description);
+        return {
+            rank: stored.rank,
+            name,
+            linkedinUrl: canonical.linkedinUrl,
+            linkedinSlug: canonical.linkedinSlug,
+            ...(imageUrl ? { imageUrl } : {}),
+            ...(vendor ? { vendor } : {}),
+            ...(category ? { category } : {}),
+            ...(description ? { description } : {})
+        };
+    });
+    products.forEach((product, index) => {
+        if (product.rank !== index + 1) {
+            throw new LinkedInProductCollectorInvariantError("rank_drift", "Artifact ranks are not contiguous.");
+        }
+    });
+    const orderChecksum = computeLinkedInProductOrderChecksum(products);
+    if (checkpoint.orderChecksum && checkpoint.orderChecksum !== orderChecksum) {
+        throw new LinkedInProductCollectorInvariantError("checksum_drift", "Checkpoint order checksum changed.");
+    }
+    const terminalPage = {
+        pageNumber: checkpoint.terminalPage.pageNumber,
+        currentUrl: checkpoint.terminalPage.currentUrl,
+        reportedTotal: checkpoint.terminalPage.reportedTotal,
+        hasNext: false,
+        visibleItemCount: checkpoint.terminalPage.visibleItemCount,
+        newProductCount: checkpoint.terminalPage.newProductCount,
+        capturedAt: checkpoint.terminalPage.capturedAt
+    };
+    return {
+        schemaVersion: ARTIFACT_SCHEMA_VERSION,
+        kind: "linkedin_product_search_snapshot",
+        complete: true,
+        source: {
+            queryUrl: checkpoint.queryUrl,
+            queryHash: checkpoint.queryHash
+        },
+        capture: {
+            startedAt: checkpoint.startedAt,
+            completedAt: checkpoint.completedAt,
+            approximateReportedTotal: checkpoint.approximateReportedTotal,
+            pagesAccepted: checkpoint.pagesAccepted,
+            terminalPage
+        },
+        productCount: products.length,
+        orderChecksumAlgorithm: "sha256",
+        orderChecksum,
+        products
+    };
+}
+function rawVisibleProductCard(card) {
+    const { rank: _rank, ...normalized } = normalizeVisibleProductCard(card, 1);
+    return normalized;
+}
+function sanitizeTerminalErrorUrl(currentUrl) {
+    let parsed;
+    try {
+        parsed = new URL(currentUrl);
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", "The browser reported an invalid terminal URL.");
+    }
+    if (parsed.protocol !== "https:" ||
+        parsed.port !== "" ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        !["linkedin.com", "www.linkedin.com"].includes(parsed.hostname.toLowerCase())) {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", "A terminal browser error must come from a LinkedIn page.");
+    }
+    return `https://www.linkedin.com${parsed.pathname}`;
+}
+function terminalStopMessage(code) {
+    switch (code) {
+        case "auth_required":
+            return "The signed-in LinkedIn session is no longer available.";
+        case "challenge":
+            return "LinkedIn displayed a checkpoint or challenge.";
+        case "rate_limited":
+            return "LinkedIn rate-limited the product search.";
+        case "interrupted":
+            return "The browser worker was interrupted.";
+        case "unexpected_page":
+            return "The browser reached an unexpected LinkedIn page.";
+    }
+}
+async function ensureParent(filePath) {
+    await mkdir(path.dirname(path.resolve(filePath)), { recursive: true });
+}
+async function writePrivateJsonAtomic(filePath, value) {
+    const resolved = path.resolve(filePath);
+    await ensureParent(resolved);
+    const temporary = `${resolved}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, resolved);
+    await chmod(resolved, 0o600);
+}
+async function appendPrivateJsonLine(filePath, value) {
+    const resolved = path.resolve(filePath);
+    await ensureParent(resolved);
+    await appendFile(resolved, `${JSON.stringify(value)}\n`, { encoding: "utf8", mode: 0o600 });
+    await chmod(resolved, 0o600);
+}
+async function readCheckpoint(filePath) {
+    try {
+        const value = JSON.parse(await readFile(path.resolve(filePath), "utf8"));
+        if (value.schemaVersion !== CHECKPOINT_SCHEMA_VERSION || !Array.isArray(value.products)) {
+            throw new Error("Unsupported LinkedIn product collector checkpoint.");
+        }
+        assertValidCheckpoint(value);
+        return value;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function assertValidCheckpoint(checkpoint) {
+    if (normalizeLinkedInProductSearchUrl(checkpoint.queryUrl) !== checkpoint.queryUrl) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint query URL is invalid.");
+    }
+    if (!/^[a-f0-9]{64}$/.test(checkpoint.queryHash)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint query hash is invalid.");
+    }
+    if (!["collecting", "complete", "failed"].includes(checkpoint.status)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint status is invalid.");
+    }
+    if (!Number.isInteger(checkpoint.nextPageNumber) ||
+        checkpoint.nextPageNumber < 1 ||
+        !Number.isInteger(checkpoint.pagesAccepted) ||
+        checkpoint.pagesAccepted < 0 ||
+        !Number.isInteger(checkpoint.tasksIssued) ||
+        checkpoint.tasksIssued < 0) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint counters are invalid.");
+    }
+    if (checkpoint.tasksIssued < checkpoint.pagesAccepted) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint has more accepted pages than issued browser tasks.");
+    }
+    assertIsoTimestamp(checkpoint.startedAt, "startedAt");
+    assertIsoTimestamp(checkpoint.updatedAt, "updatedAt");
+    if (checkpoint.updatedAt < checkpoint.startedAt) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint timestamps are out of order.");
+    }
+    if (checkpoint.approximateReportedTotal !== null &&
+        (!Number.isInteger(checkpoint.approximateReportedTotal) || checkpoint.approximateReportedTotal < 0)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint approximate reported total is invalid.");
+    }
+    const seenUrls = new Set();
+    const seenIdentities = new Set();
+    checkpoint.products.forEach((product, index) => {
+        if (product.rank !== index + 1 || !Number.isInteger(product.rank)) {
+            throw new LinkedInProductCollectorInvariantError("rank_drift", "Checkpoint ranks are not contiguous.");
+        }
+        const canonical = canonicalizeLinkedInProductUrl(product.linkedinUrl);
+        if (canonical.linkedinUrl !== product.linkedinUrl || canonical.linkedinSlug !== product.linkedinSlug) {
+            throw new LinkedInProductCollectorInvariantError("canonical_url_drift", "Checkpoint contains a non-canonical product URL.");
+        }
+        if (seenUrls.has(product.linkedinUrl)) {
+            throw new LinkedInProductCollectorInvariantError("duplicate_product", "Checkpoint contains a duplicate product URL.");
+        }
+        seenUrls.add(product.linkedinUrl);
+        if (product.identity) {
+            const identity = normalizeIdentity(product.identity);
+            if (!identity || seenIdentities.has(identity)) {
+                throw new LinkedInProductCollectorInvariantError("identity_drift", "Checkpoint contains a duplicate or invalid product identity.");
+            }
+            seenIdentities.add(identity);
+        }
+    });
+    if (checkpoint.status === "complete") {
+        if (checkpoint.pagesAccepted < 1 ||
+            checkpoint.nextPageNumber !== checkpoint.pagesAccepted ||
+            !checkpoint.terminalPage ||
+            !checkpoint.completedAt ||
+            checkpoint.lastStop !== undefined ||
+            !/^[a-f0-9]{64}$/.test(checkpoint.orderChecksum ?? "")) {
+            throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "A complete checkpoint is missing terminal evidence or its checksum.");
+        }
+        const terminal = checkpoint.terminalPage;
+        if (terminal.hasNext !== false ||
+            !Number.isInteger(terminal.pageNumber) ||
+            terminal.pageNumber !== checkpoint.pagesAccepted ||
+            terminal.currentUrl !== buildLinkedInProductSearchPageUrl(checkpoint.queryUrl, terminal.pageNumber) ||
+            !Number.isInteger(terminal.visibleItemCount) ||
+            terminal.visibleItemCount < 0 ||
+            !Number.isInteger(terminal.newProductCount) ||
+            terminal.newProductCount < 0 ||
+            terminal.newProductCount > terminal.visibleItemCount ||
+            (terminal.reportedTotal !== null &&
+                (!Number.isInteger(terminal.reportedTotal) || terminal.reportedTotal < 0))) {
+            throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Complete checkpoint terminal-page evidence is invalid.");
+        }
+        assertIsoTimestamp(terminal.capturedAt, "terminalPage.capturedAt");
+        assertIsoTimestamp(checkpoint.completedAt, "completedAt");
+        if (terminal.capturedAt !== checkpoint.completedAt || checkpoint.completedAt !== checkpoint.updatedAt) {
+            throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Complete checkpoint capture timestamps disagree.");
+        }
+        if (computeLinkedInProductOrderChecksum(checkpoint.products) !== checkpoint.orderChecksum) {
+            throw new LinkedInProductCollectorInvariantError("checksum_drift", "Checkpoint order checksum changed.");
+        }
+    }
+    else {
+        if (checkpoint.nextPageNumber !== checkpoint.pagesAccepted + 1 ||
+            checkpoint.terminalPage !== undefined ||
+            checkpoint.completedAt !== undefined ||
+            checkpoint.orderChecksum !== undefined) {
+            throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Incomplete checkpoint state is internally inconsistent.");
+        }
+        if (checkpoint.lastStop) {
+            if (typeof checkpoint.lastStop.reason !== "string" ||
+                checkpoint.lastStop.reason.trim() === "" ||
+                !Number.isInteger(checkpoint.lastStop.pageNumber) ||
+                checkpoint.lastStop.pageNumber !== checkpoint.nextPageNumber) {
+                throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint stop evidence is invalid.");
+            }
+            assertIsoTimestamp(checkpoint.lastStop.at, "lastStop.at");
+        }
+    }
+}
+function assertIsoTimestamp(value, field) {
+    if (typeof value !== "string") {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", `Checkpoint ${field} is not a timestamp.`);
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.valueOf()) || parsed.toISOString() !== value) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", `Checkpoint ${field} is not canonical ISO time.`);
+    }
+}
+async function fileExists(filePath) {
+    try {
+        await access(path.resolve(filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertRawEvidenceMatchesCheckpoint(filePath, checkpoint) {
+    const raw = await readFile(path.resolve(filePath), "utf8");
+    const lines = raw.split(/\r?\n/).filter((line) => line.trim() !== "");
+    let replay = createLinkedInProductCollectorCheckpoint(checkpoint.queryUrl, new Date(checkpoint.startedAt));
+    let acceptedPageRecords = 0;
+    for (const [index, line] of lines.entries()) {
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(line);
+        }
+        catch {
+            throw new LinkedInProductCollectorInvariantError("invalid_raw_evidence", `Raw JSONL line ${index + 1} is not valid JSON.`);
+        }
+        const record = rawEvidenceRecordSchema.parse(parsedJson);
+        if (record.queryHash !== checkpoint.queryHash) {
+            throw new LinkedInProductCollectorInvariantError("raw_query_mismatch", `Raw JSONL line ${index + 1} belongs to another query.`);
+        }
+        assertIsoTimestamp(record.receivedAt, `raw line ${index + 1} receivedAt`);
+        if (record.type === "terminal_error") {
+            if (replay.status !== "collecting" || record.pageNumber !== replay.nextPageNumber) {
+                throw new LinkedInProductCollectorInvariantError("invalid_raw_evidence", `Raw terminal error on line ${index + 1} is out of sequence.`);
+            }
+            continue;
+        }
+        if (record.pageNumber !== replay.nextPageNumber) {
+            throw new LinkedInProductCollectorInvariantError("invalid_raw_evidence", `Raw page on line ${index + 1} is duplicate or out of sequence.`);
+        }
+        const items = record.items.map(({ linkedinSlug, ...item }) => {
+            const canonical = canonicalizeLinkedInProductUrl(item.linkedinUrl);
+            if (canonical.linkedinSlug !== linkedinSlug) {
+                throw new LinkedInProductCollectorInvariantError("invalid_raw_evidence", `Raw product slug on line ${index + 1} disagrees with its URL.`);
+            }
+            return item;
+        });
+        const applied = applyLinkedInProductSearchPage(replay, {
+            pageNumber: record.pageNumber,
+            currentUrl: record.currentUrl,
+            reportedTotal: record.reportedTotal,
+            hasNext: record.hasNext,
+            items
+        }, new Date(record.receivedAt));
+        if (record.visibleItemCount !== record.items.length ||
+            record.newProductCount !== applied.newProductCount ||
+            record.duplicateCount !== applied.duplicateCount) {
+            throw new LinkedInProductCollectorInvariantError("invalid_raw_evidence", `Raw page counts on line ${index + 1} do not match its normalized items.`);
+        }
+        replay = applied.checkpoint;
+        acceptedPageRecords += 1;
+    }
+    if (acceptedPageRecords !== checkpoint.pagesAccepted) {
+        throw new LinkedInProductCollectorInvariantError("missing_raw_evidence", `Raw JSONL proves ${acceptedPageRecords} pages, but the checkpoint claims ${checkpoint.pagesAccepted}.`);
+    }
+    if (JSON.stringify(replay.products) !== JSON.stringify(checkpoint.products)) {
+        throw new LinkedInProductCollectorInvariantError("raw_order_mismatch", "Raw JSONL product order does not reproduce the checkpoint.");
+    }
+    if (replay.approximateReportedTotal !== checkpoint.approximateReportedTotal ||
+        (checkpoint.status === "complete") !== (replay.status === "complete")) {
+        throw new LinkedInProductCollectorInvariantError("raw_state_mismatch", "Raw JSONL completion metadata does not reproduce the checkpoint.");
+    }
+}
+async function readRelayJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > MAX_RELAY_BODY_BYTES) {
+            throw new LinkedInProductCollectorInvariantError("body_too_large", "Relay request body is too large.");
+        }
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0)
+        throw new Error("Relay request body is empty.");
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function writeRelayJson(res, statusCode, value, origin) {
+    const body = `${JSON.stringify(value)}\n`;
+    res.writeHead(statusCode, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Content-Length": Buffer.byteLength(body),
+        "Cache-Control": "no-store",
+        "Access-Control-Allow-Origin": origin === "https://www.linkedin.com" ? origin : "https://www.linkedin.com",
+        "Access-Control-Allow-Private-Network": "true",
+        Vary: "Origin"
+    });
+    res.end(body);
+}
+function isAllowedRelayOrigin(req) {
+    const origin = req.headers.origin;
+    return origin === undefined || origin === "https://www.linkedin.com";
+}
+function closeServer(server) {
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+export async function collectLinkedInProductsViaBrowserRelay(options) {
+    const queryUrl = normalizeLinkedInProductSearchUrl(options.queryUrl);
+    const expectedQueryHash = sha256(queryUrl);
+    const resolvedPaths = [options.checkpointPath, options.rawJsonlPath, options.outPath].map((value) => path.resolve(value));
+    if (new Set(resolvedPaths).size !== resolvedPaths.length) {
+        throw new LinkedInProductCollectorInvariantError("artifact_path_conflict", "Checkpoint, raw JSONL, and complete artifact paths must be distinct.");
+    }
+    const existingCheckpoint = await readCheckpoint(options.checkpointPath);
+    const [rawExists, outExists] = await Promise.all([
+        fileExists(options.rawJsonlPath),
+        fileExists(options.outPath)
+    ]);
+    if (!existingCheckpoint && (rawExists || outExists)) {
+        throw new LinkedInProductCollectorInvariantError("orphaned_artifact", "A new collection requires unused raw JSONL and output paths. Choose new paths or restore the matching checkpoint.");
+    }
+    if (existingCheckpoint && existingCheckpoint.pagesAccepted > 0 && !rawExists) {
+        throw new LinkedInProductCollectorInvariantError("missing_raw_evidence", "The checkpoint has accepted pages but its raw JSONL evidence is missing.");
+    }
+    if (existingCheckpoint && rawExists) {
+        await assertRawEvidenceMatchesCheckpoint(options.rawJsonlPath, existingCheckpoint);
+    }
+    if (existingCheckpoint && existingCheckpoint.status !== "complete" && outExists) {
+        throw new LinkedInProductCollectorInvariantError("stale_complete_artifact", "An incomplete checkpoint cannot share a path with an existing complete artifact. Choose a new output path.");
+    }
+    let checkpoint = existingCheckpoint ?? createLinkedInProductCollectorCheckpoint(queryUrl);
+    if (checkpoint.queryUrl !== queryUrl || checkpoint.queryHash !== expectedQueryHash) {
+        throw new LinkedInProductCollectorInvariantError("checkpoint_query_mismatch", "The checkpoint belongs to a different LinkedIn product search URL.");
+    }
+    await writePrivateJsonAtomic(options.checkpointPath, checkpoint);
+    if (checkpoint.status === "complete") {
+        const artifact = buildLinkedInProductCollectionArtifact(checkpoint);
+        await writePrivateJsonAtomic(options.outPath, artifact);
+        return {
+            status: "complete",
+            complete: true,
+            queryUrl,
+            queryHash: expectedQueryHash,
+            checkpointPath: path.resolve(options.checkpointPath),
+            rawJsonlPath: path.resolve(options.rawJsonlPath),
+            outPath: path.resolve(options.outPath),
+            pagesAccepted: checkpoint.pagesAccepted,
+            productsCollected: checkpoint.products.length,
+            nextPageNumber: checkpoint.nextPageNumber,
+            orderChecksum: checkpoint.orderChecksum,
+            terminalPage: checkpoint.terminalPage
+        };
+    }
+    if (checkpoint.status === "failed") {
+        throw new LinkedInProductCollectorInvariantError("failed_checkpoint", "The checkpoint is failed. Inspect it and choose a new checkpoint path before retrying.");
+    }
+    let uniqueTasksIssuedThisRun = 0;
+    let lastIssuedPage = null;
+    let settled = false;
+    let acceptingRequests = true;
+    let idleTimer;
+    let incompleteStopPromise;
+    let resolveResult;
+    let rejectResult;
+    const resultPromise = new Promise((resolve, reject) => {
+        resolveResult = resolve;
+        rejectResult = reject;
+    });
+    let requestQueue = Promise.resolve();
+    const enqueueExclusive = (operation) => {
+        const queued = requestQueue.then(operation, operation);
+        requestQueue = queued.catch(() => undefined);
+        return queued;
+    };
+    const server = createServer((req, res) => {
+        if (!acceptingRequests) {
+            writeRelayJson(res, 410, { status: "closed" }, req.headers.origin);
+            return;
+        }
+        const execute = async () => {
+            try {
+                await handleRequest(req, res);
+            }
+            catch (error) {
+                const browserInputError = error instanceof LinkedInProductCollectorInvariantError || error instanceof z.ZodError || error instanceof SyntaxError;
+                if (!res.headersSent) {
+                    writeRelayJson(res, browserInputError ? 409 : 500, {
+                        status: "rejected",
+                        error: error instanceof Error ? error.message : String(error)
+                    }, req.headers.origin);
+                }
+                if (!browserInputError)
+                    await abortWithError(error);
+            }
+        };
+        void enqueueExclusive(execute);
+    });
+    const makeResult = (status, reason) => ({
+        status,
+        complete: status === "complete",
+        ...(reason ? { reason } : {}),
+        queryUrl,
+        queryHash: expectedQueryHash,
+        checkpointPath: path.resolve(options.checkpointPath),
+        rawJsonlPath: path.resolve(options.rawJsonlPath),
+        outPath: status === "complete" ? path.resolve(options.outPath) : null,
+        pagesAccepted: checkpoint.pagesAccepted,
+        productsCollected: checkpoint.products.length,
+        nextPageNumber: checkpoint.nextPageNumber,
+        ...(checkpoint.orderChecksum ? { orderChecksum: checkpoint.orderChecksum } : {}),
+        ...(checkpoint.terminalPage ? { terminalPage: checkpoint.terminalPage } : {})
+    });
+    const finish = async (status, reason) => {
+        if (settled)
+            return;
+        settled = true;
+        acceptingRequests = false;
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        process.off("SIGINT", handleSigint);
+        process.off("SIGTERM", handleSigterm);
+        await closeServer(server);
+        resolveResult?.(makeResult(status, reason));
+    };
+    const abortWithError = async (error) => {
+        if (settled)
+            return;
+        settled = true;
+        acceptingRequests = false;
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        process.off("SIGINT", handleSigint);
+        process.off("SIGTERM", handleSigterm);
+        await closeServer(server);
+        rejectResult?.(error);
+    };
+    const stopIncomplete = (reason, message) => {
+        acceptingRequests = false;
+        if (incompleteStopPromise)
+            return incompleteStopPromise;
+        incompleteStopPromise = (async () => {
+            if (settled)
+                return;
+            const now = new Date().toISOString();
+            checkpoint = {
+                ...checkpoint,
+                updatedAt: now,
+                lastStop: {
+                    reason,
+                    at: now,
+                    pageNumber: checkpoint.nextPageNumber,
+                    ...(message ? { message } : {})
+                }
+            };
+            await writePrivateJsonAtomic(options.checkpointPath, checkpoint);
+            await finish("incomplete", reason);
+        })();
+        return incompleteStopPromise;
+    };
+    const requestIncompleteStop = (reason, message) => {
+        acceptingRequests = false;
+        return enqueueExclusive(async () => {
+            if (settled)
+                return;
+            if (checkpoint.status === "complete") {
+                await finish("complete");
+                return;
+            }
+            await stopIncomplete(reason, message);
+        });
+    };
+    function resetIdleTimer() {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+            void requestIncompleteStop("idle_timeout", "No browser relay activity arrived before the local timeout.").catch((error) => {
+                rejectResult?.(error);
+            });
+        }, options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS);
+        idleTimer.unref();
+    }
+    async function handleRequest(req, res) {
+        if (!acceptingRequests) {
+            writeRelayJson(res, 410, { status: "closed" }, req.headers.origin);
+            return;
+        }
+        if (!isAllowedRelayOrigin(req)) {
+            writeRelayJson(res, 403, { status: "rejected", error: "Relay origin is not allowed." });
+            return;
+        }
+        resetIdleTimer();
+        const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, {
+                "Access-Control-Allow-Origin": "https://www.linkedin.com",
+                "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+                "Access-Control-Allow-Headers": "Content-Type",
+                "Access-Control-Allow-Private-Network": "true",
+                "Access-Control-Max-Age": "600",
+                Vary: "Origin"
+            });
+            res.end();
+            return;
+        }
+        if (req.method === "GET" && requestUrl.pathname === "/health") {
+            writeRelayJson(res, 200, { status: "ok", queryHash: expectedQueryHash }, req.headers.origin);
+            return;
+        }
+        if (req.method === "GET" && requestUrl.pathname === "/task") {
+            if (options.maxPages !== undefined && checkpoint.nextPageNumber > options.maxPages) {
+                acceptingRequests = false;
+                writeRelayJson(res, 200, { status: "incomplete", reason: "page_limit" }, req.headers.origin);
+                res.once("finish", () => void requestIncompleteStop("page_limit"));
+                return;
+            }
+            if (options.maxRequests !== undefined &&
+                uniqueTasksIssuedThisRun >= options.maxRequests &&
+                lastIssuedPage !== checkpoint.nextPageNumber) {
+                acceptingRequests = false;
+                writeRelayJson(res, 200, { status: "incomplete", reason: "request_limit" }, req.headers.origin);
+                res.once("finish", () => void requestIncompleteStop("request_limit"));
+                return;
+            }
+            if (lastIssuedPage !== checkpoint.nextPageNumber) {
+                uniqueTasksIssuedThisRun += 1;
+                lastIssuedPage = checkpoint.nextPageNumber;
+                checkpoint = { ...checkpoint, tasksIssued: checkpoint.tasksIssued + 1, updatedAt: new Date().toISOString() };
+                await writePrivateJsonAtomic(options.checkpointPath, checkpoint);
+            }
+            writeRelayJson(res, 200, {
+                status: "task",
+                queryHash: expectedQueryHash,
+                pageNumber: checkpoint.nextPageNumber,
+                currentUrl: buildLinkedInProductSearchPageUrl(queryUrl, checkpoint.nextPageNumber),
+                productsAccepted: checkpoint.products.length
+            }, req.headers.origin);
+            return;
+        }
+        if (req.method === "POST" && requestUrl.pathname === "/page") {
+            const submission = linkedInProductPageSubmissionSchema.parse(await readRelayJson(req));
+            if (submission.pageNumber !== checkpoint.nextPageNumber) {
+                throw new LinkedInProductCollectorInvariantError("out_of_order_page", `Expected page ${checkpoint.nextPageNumber}, received page ${submission.pageNumber}.`);
+            }
+            if (lastIssuedPage !== submission.pageNumber) {
+                throw new LinkedInProductCollectorInvariantError("unleased_page", "Poll GET /task before posting the expected browser page.");
+            }
+            if ("error" in submission) {
+                acceptingRequests = false;
+                const sanitizedCurrentUrl = sanitizeTerminalErrorUrl(submission.currentUrl);
+                const receivedAt = new Date().toISOString();
+                await appendPrivateJsonLine(options.rawJsonlPath, {
+                    type: "terminal_error",
+                    queryHash: expectedQueryHash,
+                    pageNumber: submission.pageNumber,
+                    currentUrl: sanitizedCurrentUrl,
+                    error: { code: submission.error.code },
+                    receivedAt
+                });
+                writeRelayJson(res, 202, { status: "checkpointed", complete: false }, req.headers.origin);
+                res.once("finish", () => {
+                    void requestIncompleteStop(submission.error.code, terminalStopMessage(submission.error.code)).catch((error) => rejectResult?.(error));
+                });
+                return;
+            }
+            const sanitizedCurrentUrl = assertExpectedLinkedInSearchPage(submission.currentUrl, checkpoint.queryUrl, submission.pageNumber);
+            let applied;
+            try {
+                applied = applyLinkedInProductSearchPage(checkpoint, submission);
+            }
+            catch (error) {
+                if (error instanceof LinkedInProductCollectorInvariantError && error.code === "identity_drift") {
+                    acceptingRequests = false;
+                    const now = new Date().toISOString();
+                    checkpoint = {
+                        ...checkpoint,
+                        status: "failed",
+                        updatedAt: now,
+                        lastStop: { reason: error.code, at: now, pageNumber: checkpoint.nextPageNumber, message: error.message }
+                    };
+                    await writePrivateJsonAtomic(options.checkpointPath, checkpoint);
+                    writeRelayJson(res, 409, { status: "rejected", complete: false, error: error.message }, req.headers.origin);
+                    res.once("finish", () => void finish("incomplete", error.code));
+                    return;
+                }
+                throw error;
+            }
+            await appendPrivateJsonLine(options.rawJsonlPath, {
+                type: "page",
+                queryHash: expectedQueryHash,
+                pageNumber: submission.pageNumber,
+                currentUrl: sanitizedCurrentUrl,
+                reportedTotal: submission.reportedTotal ?? null,
+                hasNext: submission.hasNext,
+                items: submission.items.map(rawVisibleProductCard),
+                visibleItemCount: submission.items.length,
+                newProductCount: applied.newProductCount,
+                duplicateCount: applied.duplicateCount,
+                receivedAt: applied.checkpoint.updatedAt
+            });
+            checkpoint = applied.checkpoint;
+            await writePrivateJsonAtomic(options.checkpointPath, checkpoint);
+            if (checkpoint.status === "complete") {
+                const artifact = buildLinkedInProductCollectionArtifact(checkpoint);
+                await writePrivateJsonAtomic(options.outPath, artifact);
+                acceptingRequests = false;
+            }
+            lastIssuedPage = null;
+            writeRelayJson(res, 202, {
+                status: checkpoint.status === "complete" ? "complete" : "accepted",
+                complete: checkpoint.status === "complete",
+                pageNumber: submission.pageNumber,
+                newProductCount: applied.newProductCount,
+                duplicateCount: applied.duplicateCount,
+                productsAccepted: checkpoint.products.length,
+                nextPageNumber: checkpoint.nextPageNumber
+            }, req.headers.origin);
+            if (checkpoint.status === "complete") {
+                res.once("finish", () => void finish("complete"));
+            }
+            else if (options.maxPages !== undefined && checkpoint.nextPageNumber > options.maxPages) {
+                acceptingRequests = false;
+                res.once("finish", () => void requestIncompleteStop("page_limit"));
+            }
+            else if (options.maxRequests !== undefined && uniqueTasksIssuedThisRun >= options.maxRequests) {
+                acceptingRequests = false;
+                res.once("finish", () => void requestIncompleteStop("request_limit"));
+            }
+            return;
+        }
+        writeRelayJson(res, 404, { status: "not_found" }, req.headers.origin);
+    }
+    const handleSigint = () => {
+        void requestIncompleteStop("interrupted", "The collector received SIGINT.").catch((error) => rejectResult?.(error));
+    };
+    const handleSigterm = () => {
+        void requestIncompleteStop("interrupted", "The collector received SIGTERM.").catch((error) => rejectResult?.(error));
+    };
+    process.once("SIGINT", handleSigint);
+    process.once("SIGTERM", handleSigterm);
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.relayPort, "127.0.0.1", () => resolve());
+        });
+        resetIdleTimer();
+        const address = server.address();
+        if (!address || typeof address === "string")
+            throw new Error("The browser relay did not bind to TCP.");
+        options.onListening?.({
+            host: "127.0.0.1",
+            port: address.port,
+            taskUrl: `http://127.0.0.1:${address.port}/task`,
+            pageUrl: `http://127.0.0.1:${address.port}/page`
+        });
+        return await resultPromise;
+    }
+    catch (error) {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        process.off("SIGINT", handleSigint);
+        process.off("SIGTERM", handleSigterm);
+        if (server.listening)
+            await closeServer(server);
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesprompter-cli",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "Sales workflow CLI for guided lead generation, enrichment, scoring, and sync.",
   "author": "Daniel Sinewe <hello@danielsinewe.com>",
   "type": "module",