salesprompter-cli 0.1.68 → 0.1.69

package/README.md

@@ -139,6 +139,19 @@ salesprompter products:collect \
 
 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.
 
+Enrich that proven order with public product-page details, without changing its ranks or uploading it:
+
+```bash
+salesprompter products:collect-details \
+  --catalog ./data/products.complete.json \
+  --checkpoint ./data/products.details.checkpoint.json \
+  --raw-jsonl ./data/products.details.raw.jsonl \
+  --out ./data/products.with-details.json \
+  --relay-port 43118
+```
+
+The detail worker uses the same local `GET /task` lease protocol and posts only allowlisted product fields to `POST /detail`. Public URLs must be HTTPS; product images are capped at 2,048 characters, other URLs at 4,096, descriptions at 10,000, other strings at 200, roles/features at 100 entries, and customer companies at 50. The final artifact is created only after every rank has either a complete detail page or explicit unavailable-page proof.
+
 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 { collectLinkedInProductDetailsViaBrowserRelay } from "./linkedin-product-details.js";
 import { collectLinkedInProductsViaBrowserRelay } from "./linkedin-product-search.js";
 import { crawlLinkedInProductCategory } from "./linkedin-products.js";
 import { claimLinkedInSessionCookieForCli, claimValidatedSalesNavigatorSessionCookieForCli, createLinkedInSessionSupabaseClient, recordLinkedInSessionCookieAudit, resolveConfiguredEnvValue } from "./linkedin-session.js";
@@ -626,7 +627,7 @@ const cliPacks = [
         slug: "research",
         title: "Research",
         summary: "Scrape markets and enrich companies before outreach.",
-        commands: ["products:collect", "market:scrape", "companies:enrich"],
+        commands: ["products:collect", "products:collect-details", "market:scrape", "companies:enrich"],
         installStatus: "included"
     },
     {
@@ -677,6 +678,7 @@ const helpAliasByCommandName = new Map([
     ["linkedin-companies:scrape-local", "companies:scrape-linkedin"],
     ["dealroom-companies:scrape-local", "companies:scrape-dealroom"],
     ["linkedin-products:collect", "products:collect"],
+    ["linkedin-products:collect-details", "products:collect-details"],
     ["linkedin-products:scrape", "market:scrape"],
     ["salesnav:from-product-category", "leads:discover"],
     ["salesnav:people:collect", "leads:collect"],
@@ -728,6 +730,7 @@ const helpVisibleCommandNames = new Set([
     "linkedin-companies:scrape-local",
     "dealroom-companies:scrape-local",
     "linkedin-products:collect",
+    "linkedin-products:collect-details",
     "linkedin-products:scrape",
     "salesnav:from-product-category",
     "salesnav:people:collect",
@@ -15349,6 +15352,38 @@ program
     });
     printOutput(result);
 });
+program
+    .command("linkedin-products:collect-details")
+    .alias("products:collect-details")
+    .description("Enrich a proven LinkedIn product ranking locally through a resumable loopback browser relay.")
+    .requiredOption("--catalog <path>", "Complete products:collect ranking artifact path")
+    .requiredOption("--checkpoint <path>", "Private resumable product-detail checkpoint JSON path")
+    .requiredOption("--raw-jsonl <path>", "Private append-only normalized product-detail evidence path")
+    .requiredOption("--out <path>", "Complete public-fields-only enriched artifact path")
+    .requiredOption("--relay-port <number>", "Loopback relay port for GET /task and POST /detail")
+    .option("--max-requests <number>", "Optional number of unique product-detail tasks to issue in this run")
+    .action(async (options) => {
+    const relayPort = z.coerce.number().int().min(1).max(65_535).parse(options.relayPort);
+    const maxRequests = options.maxRequests === undefined
+        ? undefined
+        : z.coerce.number().int().min(1).max(100_000).parse(options.maxRequests);
+    const idleTimeoutMs = process.env.SALESPROMPTER_LINKEDIN_PRODUCT_DETAILS_RELAY_IDLE_TIMEOUT_MS
+        ? z.coerce.number().int().min(100).max(86_400_000).parse(process.env.SALESPROMPTER_LINKEDIN_PRODUCT_DETAILS_RELAY_IDLE_TIMEOUT_MS)
+        : undefined;
+    const result = await collectLinkedInProductDetailsViaBrowserRelay({
+        catalogPath: path.resolve(String(options.catalog)),
+        checkpointPath: path.resolve(String(options.checkpoint)),
+        rawJsonlPath: path.resolve(String(options.rawJsonl)),
+        outPath: path.resolve(String(options.out)),
+        relayPort,
+        maxRequests,
+        idleTimeoutMs,
+        onListening: ({ taskUrl, detailUrl }) => {
+            writeProgress(`LinkedIn product detail relay ready: GET ${taskUrl} and POST ${detailUrl}`);
+        }
+    });
+    printOutput(result);
+});
 program
     .command("linkedin-products:scrape")
     .alias("market:scrape")

package/dist/linkedin-product-details.js

@@ -0,0 +1,1203 @@
+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";
+import { buildLinkedInProductSearchPageUrl, canonicalizeLinkedInProductUrl, computeLinkedInProductOrderChecksum, LinkedInProductCollectorInvariantError, normalizeLinkedInProductSearchUrl } from "./linkedin-product-search.js";
+const CHECKPOINT_SCHEMA_VERSION = 1;
+const ENRICHED_ARTIFACT_SCHEMA_VERSION = 2;
+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 httpsUrl = (max) => z
+    .string()
+    .trim()
+    .url()
+    .max(max)
+    .refine((value) => {
+    const parsed = new URL(value);
+    return parsed.protocol === "https:" && parsed.username === "" && parsed.password === "";
+}, "Public URLs must use HTTPS without embedded credentials.");
+const optionalPublicUrl = httpsUrl(4_096).optional();
+const optionalProductImageUrl = httpsUrl(2_048).optional();
+const rankingProductSchema = z
+    .object({
+    rank: z.number().int().min(1),
+    name: nonEmptyText(200),
+    linkedinUrl: nonEmptyText(4_096),
+    linkedinSlug: nonEmptyText(720),
+    imageUrl: optionalProductImageUrl,
+    vendor: nonEmptyText(200).optional(),
+    category: nonEmptyText(200).optional(),
+    description: nonEmptyText(10_000).optional()
+})
+    .strict();
+const terminalPageSchema = z
+    .object({
+    pageNumber: z.number().int().min(1),
+    currentUrl: nonEmptyText(8_192),
+    reportedTotal: z.number().int().min(0).nullable(),
+    hasNext: z.literal(false),
+    visibleItemCount: z.number().int().min(0),
+    newProductCount: z.number().int().min(0),
+    capturedAt: nonEmptyText(100)
+})
+    .strict();
+const rankingArtifactSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("linkedin_product_search_snapshot"),
+    complete: z.literal(true),
+    source: z
+        .object({
+        queryUrl: nonEmptyText(8_192),
+        queryHash: z.string().regex(/^[a-f0-9]{64}$/)
+    })
+        .strict(),
+    capture: z
+        .object({
+        startedAt: nonEmptyText(100),
+        completedAt: nonEmptyText(100),
+        approximateReportedTotal: z.number().int().min(0).nullable(),
+        pagesAccepted: z.number().int().min(1),
+        terminalPage: terminalPageSchema
+    })
+        .strict(),
+    productCount: z.number().int().min(1),
+    orderChecksumAlgorithm: z.literal("sha256"),
+    orderChecksum: z.string().regex(/^[a-f0-9]{64}$/),
+    products: z.array(rankingProductSchema).min(1).max(100_000)
+})
+    .strict();
+const intendedRolesSchema = z.array(nonEmptyText(200)).max(100);
+const featuresSchema = z.array(nonEmptyText(200)).max(100);
+const usedByCompanySchema = z
+    .object({
+    name: nonEmptyText(200),
+    linkedinUrl: nonEmptyText(4_096).optional(),
+    logoUrl: optionalPublicUrl
+})
+    .strict();
+const completeDetailInputSchema = z
+    .object({
+    name: nonEmptyText(200),
+    imageUrl: optionalProductImageUrl,
+    vendor: nonEmptyText(200).optional(),
+    category: nonEmptyText(200).optional(),
+    description: nonEmptyText(10_000).optional(),
+    websiteUrl: optionalPublicUrl,
+    vendorLinkedinUrl: nonEmptyText(4_096).optional(),
+    vendorHandle: nonEmptyText(200).optional(),
+    intendedRoles: intendedRolesSchema,
+    usedBy: z.array(usedByCompanySchema).max(50),
+    features: featuresSchema
+})
+    .strict();
+export const linkedInProductUnavailableProofSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("http_status"),
+        status: z.union([z.literal(404), z.literal(410)])
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("linkedin_marker"),
+        marker: z.enum(["page_not_found", "product_unavailable"])
+    })
+        .strict()
+]);
+const relayErrorCodeSchema = z.enum([
+    "auth_required",
+    "challenge",
+    "rate_limited",
+    "interrupted",
+    "unexpected_page"
+]);
+const completeDetailSubmissionSchema = z
+    .object({
+    rank: z.number().int().min(1),
+    currentUrl: nonEmptyText(8_192),
+    detail: completeDetailInputSchema
+})
+    .strict();
+const unavailableDetailSubmissionSchema = z
+    .object({
+    rank: z.number().int().min(1),
+    currentUrl: nonEmptyText(8_192),
+    unavailable: z
+        .object({
+        code: z.literal("product_unavailable"),
+        proof: linkedInProductUnavailableProofSchema
+    })
+        .strict()
+})
+    .strict();
+const terminalErrorSubmissionSchema = z
+    .object({
+    rank: z.number().int().min(1),
+    currentUrl: nonEmptyText(8_192),
+    error: z
+        .object({
+        code: relayErrorCodeSchema,
+        message: z.string().trim().max(1_000).optional()
+    })
+        .strict()
+})
+    .strict();
+export const linkedInProductDetailSubmissionSchema = z.union([
+    completeDetailSubmissionSchema,
+    unavailableDetailSubmissionSchema,
+    terminalErrorSubmissionSchema
+]);
+const storedCompleteDetailSchema = completeDetailInputSchema
+    .extend({
+    status: z.literal("complete"),
+    capturedAt: nonEmptyText(100)
+})
+    .strict();
+const storedUnavailableDetailSchema = z
+    .object({
+    status: z.literal("unavailable"),
+    capturedAt: nonEmptyText(100),
+    proof: linkedInProductUnavailableProofSchema
+})
+    .strict();
+const storedDetailSchema = z.union([storedCompleteDetailSchema, storedUnavailableDetailSchema]);
+const checkpointDetailSchema = z
+    .object({
+    rank: z.number().int().min(1),
+    linkedinUrl: nonEmptyText(4_096),
+    linkedinSlug: nonEmptyText(720),
+    detail: storedDetailSchema
+})
+    .strict();
+const checkpointSchema = z
+    .object({
+    schemaVersion: z.literal(CHECKPOINT_SCHEMA_VERSION),
+    source: z
+        .object({
+        queryHash: z.string().regex(/^[a-f0-9]{64}$/),
+        orderChecksum: z.string().regex(/^[a-f0-9]{64}$/),
+        productCount: z.number().int().min(1)
+    })
+        .strict(),
+    startedAt: nonEmptyText(100),
+    updatedAt: nonEmptyText(100),
+    status: z.enum(["collecting", "complete"]),
+    nextRank: z.number().int().min(1),
+    tasksIssued: z.number().int().min(0),
+    details: z.array(checkpointDetailSchema).max(100_000),
+    completedAt: nonEmptyText(100).optional(),
+    detailChecksum: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    lastStop: z
+        .object({
+        reason: nonEmptyText(200),
+        at: nonEmptyText(100),
+        rank: z.number().int().min(1),
+        message: z.string().trim().max(1_000).optional()
+    })
+        .strict()
+        .optional()
+})
+    .strict();
+const rawCompleteDetailResultSchema = z
+    .object({
+    status: z.literal("complete"),
+    detail: completeDetailInputSchema
+})
+    .strict();
+const rawUnavailableDetailResultSchema = z
+    .object({
+    status: z.literal("unavailable"),
+    proof: linkedInProductUnavailableProofSchema
+})
+    .strict();
+const rawDetailEvidenceSchema = z
+    .object({
+    type: z.literal("detail"),
+    orderChecksum: z.string().regex(/^[a-f0-9]{64}$/),
+    rank: z.number().int().min(1),
+    currentUrl: nonEmptyText(4_096),
+    result: z.union([rawCompleteDetailResultSchema, rawUnavailableDetailResultSchema]),
+    receivedAt: nonEmptyText(100)
+})
+    .strict();
+const rawTerminalEvidenceSchema = z
+    .object({
+    type: z.literal("terminal_error"),
+    orderChecksum: z.string().regex(/^[a-f0-9]{64}$/),
+    rank: z.number().int().min(1),
+    currentUrl: nonEmptyText(4_096),
+    error: z.object({ code: relayErrorCodeSchema }).strict(),
+    receivedAt: nonEmptyText(100)
+})
+    .strict();
+const rawEvidenceRecordSchema = z.union([rawDetailEvidenceSchema, rawTerminalEvidenceSchema]);
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(",")}}`;
+}
+function cleanText(value) {
+    const cleaned = value?.replace(/\s+/g, " ").trim();
+    return cleaned || undefined;
+}
+function uniqueText(values) {
+    const seen = new Set();
+    const output = [];
+    for (const value of values) {
+        const cleaned = cleanText(value);
+        if (!cleaned)
+            continue;
+        const key = cleaned.toLocaleLowerCase("en-US");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        output.push(cleaned);
+    }
+    return output;
+}
+function canonicalizePublicUrl(value, maxLength = 4_096) {
+    const cleaned = cleanText(value);
+    if (!cleaned)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(cleaned);
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("invalid_public_url", `Invalid public URL: ${cleaned}`);
+    }
+    if (parsed.protocol !== "https:" ||
+        parsed.username !== "" ||
+        parsed.password !== "") {
+        throw new LinkedInProductCollectorInvariantError("invalid_public_url", `Unsupported public URL: ${cleaned}`);
+    }
+    parsed.hash = "";
+    const canonical = parsed.toString();
+    if (canonical.length > maxLength) {
+        throw new LinkedInProductCollectorInvariantError("invalid_public_url", `Public URL exceeds ${maxLength} characters.`);
+    }
+    return canonical;
+}
+export function canonicalizeLinkedInCompanyUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value, "https://www.linkedin.com");
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("invalid_company_url", `Invalid LinkedIn company 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_company_url", `Company URL is outside LinkedIn: ${value}`);
+    }
+    const match = parsed.pathname.match(/^\/company\/([^/]+)\/?$/i);
+    if (!match?.[1]) {
+        throw new LinkedInProductCollectorInvariantError("invalid_company_url", `Company URL must match /company/<handle>/: ${value}`);
+    }
+    let decodedHandle;
+    try {
+        decodedHandle = decodeURIComponent(match[1]).trim().normalize("NFC").toLowerCase();
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("invalid_company_url", `Invalid encoded company handle: ${value}`);
+    }
+    if (!decodedHandle || /[\s/?#\\]/u.test(decodedHandle)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_company_url", `Invalid company handle: ${value}`);
+    }
+    const handle = encodeURIComponent(decodedHandle)
+        .replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).padStart(2, "0")}`)
+        .toLowerCase();
+    if (handle.length > 720 || !/^(?:[a-z0-9._~-]|%[0-9a-f]{2})+$/.test(handle)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_company_url", `Invalid company handle: ${handle}`);
+    }
+    return {
+        linkedinUrl: `https://www.linkedin.com/company/${handle}`,
+        handle
+    };
+}
+function normalizeVendorHandle(value) {
+    const cleaned = cleanText(value)?.normalize("NFC").toLowerCase();
+    if (!cleaned)
+        return undefined;
+    if (cleaned.length > 200 || /[\s/?#\\]/u.test(cleaned)) {
+        throw new LinkedInProductCollectorInvariantError("invalid_vendor_handle", "Vendor handle is invalid.");
+    }
+    return cleaned;
+}
+function normalizeUsedBy(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const name = cleanText(value.name);
+        if (!name)
+            continue;
+        const company = value.linkedinUrl ? canonicalizeLinkedInCompanyUrl(value.linkedinUrl) : undefined;
+        const logoUrl = canonicalizePublicUrl(value.logoUrl);
+        const key = company?.linkedinUrl ?? name.toLocaleLowerCase("en-US");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push({
+            name,
+            ...(company ? { linkedinUrl: company.linkedinUrl } : {}),
+            ...(logoUrl ? { logoUrl } : {})
+        });
+    }
+    return result;
+}
+function normalizeCompleteDetail(input, capturedAt) {
+    const name = cleanText(input.name);
+    if (!name) {
+        throw new LinkedInProductCollectorInvariantError("invalid_product_detail", "Product detail name is empty.");
+    }
+    const vendorLinkedIn = input.vendorLinkedinUrl
+        ? canonicalizeLinkedInCompanyUrl(input.vendorLinkedinUrl)
+        : undefined;
+    const suppliedVendorHandle = normalizeVendorHandle(input.vendorHandle);
+    const derivedVendorHandle = vendorLinkedIn
+        ? normalizeVendorHandle(decodeURIComponent(vendorLinkedIn.handle))
+        : undefined;
+    const imageUrl = canonicalizePublicUrl(input.imageUrl, 2_048);
+    const websiteUrl = canonicalizePublicUrl(input.websiteUrl);
+    if (vendorLinkedIn &&
+        suppliedVendorHandle &&
+        derivedVendorHandle !== suppliedVendorHandle) {
+        throw new LinkedInProductCollectorInvariantError("vendor_identity_drift", "Vendor LinkedIn URL and handle disagree.");
+    }
+    return {
+        status: "complete",
+        capturedAt,
+        name,
+        ...(imageUrl ? { imageUrl } : {}),
+        ...(cleanText(input.vendor) ? { vendor: cleanText(input.vendor) } : {}),
+        ...(cleanText(input.category) ? { category: cleanText(input.category) } : {}),
+        ...(cleanText(input.description) ? { description: cleanText(input.description) } : {}),
+        ...(websiteUrl ? { websiteUrl } : {}),
+        ...(vendorLinkedIn ? { vendorLinkedinUrl: vendorLinkedIn.linkedinUrl } : {}),
+        ...(suppliedVendorHandle || derivedVendorHandle
+            ? { vendorHandle: suppliedVendorHandle ?? derivedVendorHandle }
+            : {}),
+        intendedRoles: uniqueText(input.intendedRoles),
+        usedBy: normalizeUsedBy(input.usedBy),
+        features: uniqueText(input.features)
+    };
+}
+function assertIsoTimestamp(value, field) {
+    if (typeof value !== "string") {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", `${field} is not a timestamp.`);
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.valueOf()) || parsed.toISOString() !== value) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", `${field} is not canonical ISO time.`);
+    }
+}
+export function validateLinkedInProductRankingArtifact(input) {
+    const artifact = rankingArtifactSchema.parse(input);
+    const queryUrl = normalizeLinkedInProductSearchUrl(artifact.source.queryUrl);
+    if (queryUrl !== artifact.source.queryUrl || sha256(queryUrl) !== artifact.source.queryHash) {
+        throw new LinkedInProductCollectorInvariantError("invalid_catalog", "Ranking artifact query URL and query hash disagree.");
+    }
+    if (artifact.productCount !== artifact.products.length) {
+        throw new LinkedInProductCollectorInvariantError("invalid_catalog", "Ranking artifact product count does not match its products.");
+    }
+    assertIsoTimestamp(artifact.capture.startedAt, "catalog.capture.startedAt");
+    assertIsoTimestamp(artifact.capture.completedAt, "catalog.capture.completedAt");
+    assertIsoTimestamp(artifact.capture.terminalPage.capturedAt, "catalog.capture.terminalPage.capturedAt");
+    if (artifact.capture.completedAt !== artifact.capture.terminalPage.capturedAt ||
+        artifact.capture.startedAt > artifact.capture.completedAt ||
+        artifact.capture.terminalPage.pageNumber !== artifact.capture.pagesAccepted ||
+        artifact.capture.terminalPage.currentUrl !==
+            buildLinkedInProductSearchPageUrl(artifact.source.queryUrl, artifact.capture.terminalPage.pageNumber) ||
+        artifact.capture.terminalPage.newProductCount > artifact.capture.terminalPage.visibleItemCount) {
+        throw new LinkedInProductCollectorInvariantError("invalid_catalog", "Ranking artifact terminal-page evidence is inconsistent.");
+    }
+    const seenUrls = new Set();
+    artifact.products.forEach((product, index) => {
+        if (product.rank !== index + 1) {
+            throw new LinkedInProductCollectorInvariantError("rank_drift", "Ranking artifact ranks are not contiguous.");
+        }
+        const canonical = canonicalizeLinkedInProductUrl(product.linkedinUrl);
+        if (canonical.linkedinUrl !== product.linkedinUrl || canonical.linkedinSlug !== product.linkedinSlug) {
+            throw new LinkedInProductCollectorInvariantError("canonical_url_drift", `Ranking artifact product ${product.rank} is not canonical.`);
+        }
+        if (seenUrls.has(canonical.linkedinUrl)) {
+            throw new LinkedInProductCollectorInvariantError("duplicate_product", "Ranking artifact contains duplicate URLs.");
+        }
+        seenUrls.add(canonical.linkedinUrl);
+        if (product.imageUrl) {
+            canonicalizePublicUrl(product.imageUrl, 2_048);
+        }
+    });
+    if (computeLinkedInProductOrderChecksum(artifact.products) !== artifact.orderChecksum) {
+        throw new LinkedInProductCollectorInvariantError("checksum_drift", "Ranking artifact order checksum does not match its products.");
+    }
+    return artifact;
+}
+export async function readLinkedInProductRankingArtifact(catalogPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(path.resolve(catalogPath), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new LinkedInProductCollectorInvariantError("missing_catalog", "Ranking artifact does not exist.");
+        }
+        throw error;
+    }
+    return validateLinkedInProductRankingArtifact(parsed);
+}
+export function createLinkedInProductDetailsCheckpoint(catalog, now = new Date()) {
+    validateLinkedInProductRankingArtifact(catalog);
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: CHECKPOINT_SCHEMA_VERSION,
+        source: {
+            queryHash: catalog.source.queryHash,
+            orderChecksum: catalog.orderChecksum,
+            productCount: catalog.productCount
+        },
+        startedAt: timestamp,
+        updatedAt: timestamp,
+        status: "collecting",
+        nextRank: 1,
+        tasksIssued: 0,
+        details: []
+    };
+}
+function assertExpectedProductDetailPage(currentUrl, expectedProduct) {
+    let parsed;
+    try {
+        parsed = new URL(currentUrl);
+    }
+    catch {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", "Browser reported an invalid product 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", "Browser is not on the expected LinkedIn product page.");
+    }
+    const canonical = canonicalizeLinkedInProductUrl(currentUrl);
+    if (canonical.linkedinUrl !== expectedProduct.linkedinUrl) {
+        throw new LinkedInProductCollectorInvariantError("unexpected_page", `Expected ${expectedProduct.linkedinUrl}, received another product page.`);
+    }
+    return canonical.linkedinUrl;
+}
+export function computeLinkedInProductDetailChecksum(details) {
+    const manifest = details
+        .map((entry) => `${entry.rank}\t${entry.linkedinUrl}\t${canonicalJson(entry.detail)}`)
+        .join("\n");
+    return sha256(manifest);
+}
+export function applyLinkedInProductDetailSubmission(catalog, checkpoint, submission, now = new Date()) {
+    validateLinkedInProductRankingArtifact(catalog);
+    assertValidCheckpoint(checkpoint, catalog);
+    if (checkpoint.status !== "collecting") {
+        throw new LinkedInProductCollectorInvariantError("checkpoint_closed", "Detail checkpoint is complete.");
+    }
+    if (submission.rank !== checkpoint.nextRank) {
+        throw new LinkedInProductCollectorInvariantError("out_of_order_detail", `Expected product rank ${checkpoint.nextRank}, received ${submission.rank}.`);
+    }
+    const product = catalog.products[submission.rank - 1];
+    if (!product) {
+        throw new LinkedInProductCollectorInvariantError("invalid_rank", "Detail rank exceeds catalog size.");
+    }
+    assertExpectedProductDetailPage(submission.currentUrl, product);
+    const capturedAt = now.toISOString();
+    const detail = "detail" in submission
+        ? normalizeCompleteDetail(submission.detail, capturedAt)
+        : {
+            status: "unavailable",
+            capturedAt,
+            proof: submission.unavailable.proof
+        };
+    const accepted = {
+        rank: product.rank,
+        linkedinUrl: product.linkedinUrl,
+        linkedinSlug: product.linkedinSlug,
+        detail
+    };
+    const details = [...checkpoint.details, accepted];
+    const complete = details.length === catalog.productCount;
+    const nextCheckpoint = {
+        ...checkpoint,
+        updatedAt: capturedAt,
+        status: complete ? "complete" : "collecting",
+        nextRank: product.rank + 1,
+        tasksIssued: Math.max(checkpoint.tasksIssued, details.length),
+        details,
+        lastStop: undefined,
+        ...(complete
+            ? {
+                completedAt: capturedAt,
+                detailChecksum: computeLinkedInProductDetailChecksum(details)
+            }
+            : {
+                completedAt: undefined,
+                detailChecksum: undefined
+            })
+    };
+    return { checkpoint: nextCheckpoint, accepted };
+}
+export function buildLinkedInProductDetailsArtifact(catalog, checkpoint) {
+    validateLinkedInProductRankingArtifact(catalog);
+    assertValidCheckpoint(checkpoint, catalog);
+    if (checkpoint.status !== "complete" || !checkpoint.completedAt || !checkpoint.detailChecksum) {
+        throw new LinkedInProductCollectorInvariantError("incomplete_checkpoint", "A complete detail artifact requires every ranked product to have terminal detail evidence.");
+    }
+    const byRank = new Map(checkpoint.details.map((entry) => [entry.rank, entry]));
+    const products = catalog.products.map((product) => {
+        const stored = byRank.get(product.rank);
+        if (!stored) {
+            throw new LinkedInProductCollectorInvariantError("missing_detail", `Missing detail for rank ${product.rank}.`);
+        }
+        if (stored.detail.status === "unavailable") {
+            return {
+                ...product,
+                detailStatus: "unavailable",
+                detailsScrapedAt: stored.detail.capturedAt,
+                intendedRoles: [],
+                usedBy: [],
+                features: [],
+                unavailableProof: stored.detail.proof
+            };
+        }
+        const detail = stored.detail;
+        return {
+            ...product,
+            name: detail.name,
+            ...(detail.imageUrl ? { imageUrl: detail.imageUrl } : {}),
+            ...(detail.vendor ? { vendor: detail.vendor } : {}),
+            ...(detail.category ? { category: detail.category } : {}),
+            ...(detail.description ? { description: detail.description } : {}),
+            detailStatus: "complete",
+            detailsScrapedAt: detail.capturedAt,
+            ...(detail.websiteUrl ? { websiteUrl: detail.websiteUrl } : {}),
+            ...(detail.vendorLinkedinUrl ? { vendorLinkedinUrl: detail.vendorLinkedinUrl } : {}),
+            ...(detail.vendorHandle ? { vendorHandle: detail.vendorHandle } : {}),
+            intendedRoles: [...detail.intendedRoles],
+            usedBy: detail.usedBy.map((company) => ({ ...company })),
+            features: [...detail.features]
+        };
+    });
+    const detailChecksum = computeLinkedInProductDetailChecksum(checkpoint.details);
+    if (detailChecksum !== checkpoint.detailChecksum) {
+        throw new LinkedInProductCollectorInvariantError("checksum_drift", "Detail checkpoint checksum changed.");
+    }
+    const productsUnavailable = checkpoint.details.filter((entry) => entry.detail.status === "unavailable").length;
+    return {
+        schemaVersion: ENRICHED_ARTIFACT_SCHEMA_VERSION,
+        kind: catalog.kind,
+        complete: true,
+        source: { ...catalog.source },
+        capture: {
+            ...catalog.capture,
+            terminalPage: { ...catalog.capture.terminalPage }
+        },
+        productCount: catalog.productCount,
+        orderChecksumAlgorithm: "sha256",
+        orderChecksum: catalog.orderChecksum,
+        detailCapture: {
+            startedAt: checkpoint.startedAt,
+            completedAt: checkpoint.completedAt,
+            productsAttempted: checkpoint.details.length,
+            productsComplete: checkpoint.details.length - productsUnavailable,
+            productsUnavailable
+        },
+        detailChecksumAlgorithm: "sha256",
+        detailChecksum,
+        products
+    };
+}
+function assertValidCheckpoint(checkpoint, catalog) {
+    checkpointSchema.parse(checkpoint);
+    if (checkpoint.source.queryHash !== catalog.source.queryHash ||
+        checkpoint.source.orderChecksum !== catalog.orderChecksum ||
+        checkpoint.source.productCount !== catalog.productCount) {
+        throw new LinkedInProductCollectorInvariantError("checkpoint_catalog_mismatch", "Detail checkpoint belongs to a different ranking artifact.");
+    }
+    assertIsoTimestamp(checkpoint.startedAt, "checkpoint.startedAt");
+    assertIsoTimestamp(checkpoint.updatedAt, "checkpoint.updatedAt");
+    if (checkpoint.updatedAt < checkpoint.startedAt) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint timestamps are out of order.");
+    }
+    if (checkpoint.tasksIssued < checkpoint.details.length) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint has more details than issued tasks.");
+    }
+    checkpoint.details.forEach((entry, index) => {
+        const product = catalog.products[index];
+        if (!product ||
+            entry.rank !== index + 1 ||
+            entry.rank !== product.rank ||
+            entry.linkedinUrl !== product.linkedinUrl ||
+            entry.linkedinSlug !== product.linkedinSlug) {
+            throw new LinkedInProductCollectorInvariantError("detail_order_drift", "Checkpoint details no longer match the ranked catalog order.");
+        }
+        assertIsoTimestamp(entry.detail.capturedAt, `checkpoint.details[${index}].capturedAt`);
+    });
+    if (checkpoint.nextRank !== checkpoint.details.length + 1) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint next rank does not follow accepted details.");
+    }
+    if (checkpoint.status === "complete") {
+        if (checkpoint.details.length !== catalog.productCount ||
+            checkpoint.nextRank !== catalog.productCount + 1 ||
+            !checkpoint.completedAt ||
+            !checkpoint.detailChecksum ||
+            checkpoint.lastStop !== undefined) {
+            throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Complete detail checkpoint is missing terminal evidence.");
+        }
+        assertIsoTimestamp(checkpoint.completedAt, "checkpoint.completedAt");
+        if (checkpoint.completedAt !== checkpoint.updatedAt) {
+            throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Complete checkpoint timestamps disagree.");
+        }
+        if (computeLinkedInProductDetailChecksum(checkpoint.details) !== checkpoint.detailChecksum) {
+            throw new LinkedInProductCollectorInvariantError("checksum_drift", "Checkpoint detail checksum changed.");
+        }
+    }
+    else if (checkpoint.completedAt !== undefined || checkpoint.detailChecksum !== undefined) {
+        throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Incomplete checkpoint cannot contain completion evidence.");
+    }
+    if (checkpoint.lastStop) {
+        assertIsoTimestamp(checkpoint.lastStop.at, "checkpoint.lastStop.at");
+        if (checkpoint.lastStop.rank !== checkpoint.nextRank) {
+            throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Checkpoint stop evidence does not match the next rank.");
+        }
+    }
+}
+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 fileExists(filePath) {
+    try {
+        await access(path.resolve(filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readCheckpoint(checkpointPath, catalog) {
+    try {
+        const parsed = checkpointSchema.parse(JSON.parse(await readFile(path.resolve(checkpointPath), "utf8")));
+        assertValidCheckpoint(parsed, catalog);
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function rawResultFromStoredDetail(detail) {
+    if (detail.status === "unavailable") {
+        return { status: "unavailable", proof: detail.proof };
+    }
+    const { status: _status, capturedAt: _capturedAt, ...publicDetail } = detail;
+    return { status: "complete", detail: publicDetail };
+}
+function submissionFromRawDetail(record) {
+    if (record.result.status === "unavailable") {
+        return {
+            rank: record.rank,
+            currentUrl: record.currentUrl,
+            unavailable: {
+                code: "product_unavailable",
+                proof: record.result.proof
+            }
+        };
+    }
+    return {
+        rank: record.rank,
+        currentUrl: record.currentUrl,
+        detail: record.result.detail
+    };
+}
+async function assertRawEvidenceMatchesCheckpoint(rawJsonlPath, catalog, checkpoint) {
+    const raw = await readFile(path.resolve(rawJsonlPath), "utf8");
+    const lines = raw.split(/\r?\n/).filter((line) => line.trim() !== "");
+    let replay = createLinkedInProductDetailsCheckpoint(catalog, new Date(checkpoint.startedAt));
+    let acceptedDetails = 0;
+    for (const [index, line] of lines.entries()) {
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(line);
+        }
+        catch {
+            throw new LinkedInProductCollectorInvariantError("invalid_raw_evidence", `Raw detail JSONL line ${index + 1} is not valid JSON.`);
+        }
+        const record = rawEvidenceRecordSchema.parse(parsedJson);
+        if (record.orderChecksum !== catalog.orderChecksum) {
+            throw new LinkedInProductCollectorInvariantError("raw_catalog_mismatch", `Raw detail JSONL line ${index + 1} belongs to another ranking artifact.`);
+        }
+        assertIsoTimestamp(record.receivedAt, `raw detail line ${index + 1} receivedAt`);
+        if (record.type === "terminal_error") {
+            if (record.rank !== replay.nextRank) {
+                throw new LinkedInProductCollectorInvariantError("invalid_raw_evidence", `Raw terminal detail error on line ${index + 1} is out of sequence.`);
+            }
+            continue;
+        }
+        if (record.rank !== replay.nextRank) {
+            throw new LinkedInProductCollectorInvariantError("invalid_raw_evidence", `Raw detail on line ${index + 1} is duplicate or out of sequence.`);
+        }
+        const applied = applyLinkedInProductDetailSubmission(catalog, replay, submissionFromRawDetail(record), new Date(record.receivedAt));
+        replay = applied.checkpoint;
+        acceptedDetails += 1;
+    }
+    if (acceptedDetails !== checkpoint.details.length) {
+        throw new LinkedInProductCollectorInvariantError("missing_raw_evidence", `Raw detail JSONL proves ${acceptedDetails} products, but checkpoint claims ${checkpoint.details.length}.`);
+    }
+    if (canonicalJson(replay.details) !== canonicalJson(checkpoint.details)) {
+        throw new LinkedInProductCollectorInvariantError("raw_detail_mismatch", "Raw detail JSONL does not reproduce the checkpoint.");
+    }
+    if ((checkpoint.status === "complete") !== (replay.status === "complete")) {
+        throw new LinkedInProductCollectorInvariantError("raw_state_mismatch", "Raw detail JSONL completion state does not reproduce the checkpoint.");
+    }
+}
+function sanitizeTerminalErrorUrl(currentUrl) {
+    let parsed;
+    try {
+        parsed = new URL(currentUrl);
+    }
+    catch {
+        return "invalid-url-redacted";
+    }
+    if (parsed.protocol !== "https:" ||
+        parsed.port !== "" ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        !["linkedin.com", "www.linkedin.com"].includes(parsed.hostname.toLowerCase())) {
+        return "external-url-redacted";
+    }
+    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 product detail collection.";
+        case "interrupted":
+            return "The browser worker was interrupted.";
+        case "unexpected_page":
+            return "The browser reached an unexpected LinkedIn page.";
+    }
+}
+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()));
+}
+function detailCoverage(checkpoint) {
+    const unavailable = checkpoint.details.filter((entry) => entry.detail.status === "unavailable").length;
+    return { complete: checkpoint.details.length - unavailable, unavailable };
+}
+export async function collectLinkedInProductDetailsViaBrowserRelay(options) {
+    const catalog = await readLinkedInProductRankingArtifact(options.catalogPath);
+    const resolvedPaths = [
+        options.catalogPath,
+        options.checkpointPath,
+        options.rawJsonlPath,
+        options.outPath
+    ].map((value) => path.resolve(value));
+    if (new Set(resolvedPaths).size !== resolvedPaths.length) {
+        throw new LinkedInProductCollectorInvariantError("artifact_path_conflict", "Catalog, checkpoint, raw detail JSONL, and enriched output paths must be distinct.");
+    }
+    const existingCheckpoint = await readCheckpoint(options.checkpointPath, catalog);
+    const [rawExists, outExists] = await Promise.all([
+        fileExists(options.rawJsonlPath),
+        fileExists(options.outPath)
+    ]);
+    if (!existingCheckpoint && (rawExists || outExists)) {
+        throw new LinkedInProductCollectorInvariantError("orphaned_artifact", "A new detail collection requires unused raw and output paths.");
+    }
+    if (existingCheckpoint && existingCheckpoint.details.length > 0 && !rawExists) {
+        throw new LinkedInProductCollectorInvariantError("missing_raw_evidence", "Detail checkpoint has accepted products but raw evidence is missing.");
+    }
+    if (existingCheckpoint && rawExists) {
+        await assertRawEvidenceMatchesCheckpoint(options.rawJsonlPath, catalog, existingCheckpoint);
+    }
+    if (existingCheckpoint && existingCheckpoint.status !== "complete" && outExists) {
+        throw new LinkedInProductCollectorInvariantError("stale_complete_artifact", "Incomplete detail checkpoint cannot share an existing enriched output path.");
+    }
+    let checkpoint = existingCheckpoint ?? createLinkedInProductDetailsCheckpoint(catalog);
+    await writePrivateJsonAtomic(options.checkpointPath, checkpoint);
+    const makeResult = (status, reason) => {
+        const coverage = detailCoverage(checkpoint);
+        return {
+            status,
+            complete: status === "complete",
+            ...(reason ? { reason } : {}),
+            catalogPath: path.resolve(options.catalogPath),
+            checkpointPath: path.resolve(options.checkpointPath),
+            rawJsonlPath: path.resolve(options.rawJsonlPath),
+            outPath: status === "complete" ? path.resolve(options.outPath) : null,
+            orderChecksum: catalog.orderChecksum,
+            ...(checkpoint.detailChecksum ? { detailChecksum: checkpoint.detailChecksum } : {}),
+            productsTotal: catalog.productCount,
+            detailsCollected: checkpoint.details.length,
+            detailsComplete: coverage.complete,
+            productsUnavailable: coverage.unavailable,
+            nextRank: checkpoint.nextRank
+        };
+    };
+    if (checkpoint.status === "complete") {
+        await writePrivateJsonAtomic(options.outPath, buildLinkedInProductDetailsArtifact(catalog, checkpoint));
+        return makeResult("complete");
+    }
+    let uniqueTasksIssuedThisRun = 0;
+    let lastIssuedRank = 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 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,
+                    rank: checkpoint.nextRank,
+                    ...(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 detail relay activity arrived before the local timeout.").catch((error) => rejectResult?.(error));
+        }, options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS);
+        idleTimer.unref();
+    }
+    async function handleUnexpectedPage(submission, error, res, origin) {
+        acceptingRequests = false;
+        const receivedAt = new Date().toISOString();
+        await appendPrivateJsonLine(options.rawJsonlPath, {
+            type: "terminal_error",
+            orderChecksum: catalog.orderChecksum,
+            rank: submission.rank,
+            currentUrl: sanitizeTerminalErrorUrl(submission.currentUrl),
+            error: { code: "unexpected_page" },
+            receivedAt
+        });
+        writeRelayJson(res, 202, { status: "checkpointed", complete: false }, origin);
+        res.once("finish", () => {
+            void requestIncompleteStop("unexpected_page", error.message).catch((failure) => rejectResult?.(failure));
+        });
+    }
+    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", orderChecksum: catalog.orderChecksum }, req.headers.origin);
+            return;
+        }
+        if (req.method === "GET" && requestUrl.pathname === "/task") {
+            if (options.maxRequests !== undefined &&
+                uniqueTasksIssuedThisRun >= options.maxRequests &&
+                lastIssuedRank !== checkpoint.nextRank) {
+                acceptingRequests = false;
+                writeRelayJson(res, 200, { status: "incomplete", reason: "request_limit" }, req.headers.origin);
+                res.once("finish", () => void requestIncompleteStop("request_limit"));
+                return;
+            }
+            const product = catalog.products[checkpoint.nextRank - 1];
+            if (!product) {
+                throw new LinkedInProductCollectorInvariantError("invalid_checkpoint", "Next detail product is missing.");
+            }
+            if (lastIssuedRank !== checkpoint.nextRank) {
+                uniqueTasksIssuedThisRun += 1;
+                lastIssuedRank = checkpoint.nextRank;
+                checkpoint = {
+                    ...checkpoint,
+                    tasksIssued: checkpoint.tasksIssued + 1,
+                    updatedAt: new Date().toISOString()
+                };
+                await writePrivateJsonAtomic(options.checkpointPath, checkpoint);
+            }
+            writeRelayJson(res, 200, {
+                status: "task",
+                taskType: "linkedin_product_detail",
+                orderChecksum: catalog.orderChecksum,
+                rank: product.rank,
+                productCount: catalog.productCount,
+                currentUrl: product.linkedinUrl,
+                productName: product.name,
+                detailsAccepted: checkpoint.details.length
+            }, req.headers.origin);
+            return;
+        }
+        if (req.method === "POST" && requestUrl.pathname === "/detail") {
+            const submission = linkedInProductDetailSubmissionSchema.parse(await readRelayJson(req));
+            if (submission.rank !== checkpoint.nextRank) {
+                throw new LinkedInProductCollectorInvariantError("out_of_order_detail", `Expected product rank ${checkpoint.nextRank}, received ${submission.rank}.`);
+            }
+            if (lastIssuedRank !== submission.rank) {
+                throw new LinkedInProductCollectorInvariantError("unleased_detail", "Poll GET /task before posting the expected product detail.");
+            }
+            if ("error" in submission) {
+                acceptingRequests = false;
+                const receivedAt = new Date().toISOString();
+                await appendPrivateJsonLine(options.rawJsonlPath, {
+                    type: "terminal_error",
+                    orderChecksum: catalog.orderChecksum,
+                    rank: submission.rank,
+                    currentUrl: sanitizeTerminalErrorUrl(submission.currentUrl),
+                    error: { code: submission.error.code },
+                    receivedAt
+                });
+                writeRelayJson(res, 202, { status: "checkpointed", complete: false }, req.headers.origin);
+                res.once("finish", () => {
+                    void requestIncompleteStop(submission.error.code, submission.error.message ?? terminalStopMessage(submission.error.code)).catch((error) => rejectResult?.(error));
+                });
+                return;
+            }
+            let applied;
+            try {
+                applied = applyLinkedInProductDetailSubmission(catalog, checkpoint, submission);
+            }
+            catch (error) {
+                if (error instanceof LinkedInProductCollectorInvariantError && error.code === "unexpected_page") {
+                    await handleUnexpectedPage(submission, error, res, req.headers.origin);
+                    return;
+                }
+                throw error;
+            }
+            await appendPrivateJsonLine(options.rawJsonlPath, {
+                type: "detail",
+                orderChecksum: catalog.orderChecksum,
+                rank: submission.rank,
+                currentUrl: applied.accepted.linkedinUrl,
+                result: rawResultFromStoredDetail(applied.accepted.detail),
+                receivedAt: applied.accepted.detail.capturedAt
+            });
+            checkpoint = applied.checkpoint;
+            await writePrivateJsonAtomic(options.checkpointPath, checkpoint);
+            if (checkpoint.status === "complete") {
+                await writePrivateJsonAtomic(options.outPath, buildLinkedInProductDetailsArtifact(catalog, checkpoint));
+                acceptingRequests = false;
+            }
+            lastIssuedRank = null;
+            writeRelayJson(res, 202, {
+                status: checkpoint.status === "complete" ? "complete" : "accepted",
+                complete: checkpoint.status === "complete",
+                rank: submission.rank,
+                detailStatus: applied.accepted.detail.status,
+                detailsAccepted: checkpoint.details.length,
+                nextRank: checkpoint.nextRank
+            }, req.headers.origin);
+            if (checkpoint.status === "complete") {
+                res.once("finish", () => void finish("complete"));
+            }
+            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", "Detail collector received SIGINT.").catch((error) => rejectResult?.(error));
+    };
+    const handleSigterm = () => {
+        void requestIncompleteStop("interrupted", "Detail 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("LinkedIn product detail 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`,
+            detailUrl: `http://127.0.0.1:${address.port}/detail`
+        });
+        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.68",
+  "version": "0.1.69",
   "description": "Sales workflow CLI for guided lead generation, enrichment, scoring, and sync.",
   "author": "Daniel Sinewe <hello@danielsinewe.com>",
   "type": "module",