salesprompter-cli 0.1.67 → 0.1.69

package/README.md

@@ -97,11 +97,12 @@ salesprompter affiliate:launch \
   --linkedin-url "https://www.linkedin.com/sales/search/people?query=..." \
   --max-results 100
 
-# End to end: collect, enrich emails, write a sequence, and create a draft Instantly campaign
-salesprompter affiliate:run \
+# End to end: collect, exclude customers, deduplicate, verify, enrich, and create a draft
+salesprompter affiliate:grow \
   --affiliate-link "https://example.com/?ref=you" \
   --linkedin-url "https://www.linkedin.com/sales/search/people?query=..." \
   --max-results 100 \
+  --seed-profile "https://www.linkedin.com/in/existing-customer" \
   --steps 3 \
   --timing-mode custom \
   --daily-limit 25 \
@@ -138,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
@@ -158,7 +172,9 @@ the app's CLI imports view.
 
 - Use your own authorized data access and workspace credentials.
 - Respect provider terms and customer data boundaries.
-- `affiliate:run` uses direct email enrichment first, then Phantombuster Email Finder for unresolved people before creating a draft Instantly campaign.
+- `affiliate:grow` is an alias for `affiliate:run`. It excludes repeated `--seed-profile` customers, removes profiles already stored in prior workspace affiliate audiences, and verifies the final persisted count before preparing Instantly.
+- If every collected profile is known or excluded, no audience or Instantly campaign is created. A stale Sales Navigator session also fails before persistence with a safe retry instruction.
+- Affiliate outreach uses direct email enrichment first, then Phantombuster Email Finder for unresolved people before creating a draft Instantly campaign.
 - Affiliate preparation uses exactly three emails with three observable variants per step; `affiliate:regenerate-sequence` rebuilds and syncs them through the Salesprompter app.
 - `affiliate:list` shows safe workspace summaries. `affiliate:analytics` shows aggregate and step/variant outcomes without exposing lead data; unsupported per-step meeting and won fields render as `n/a`.
 - `affiliate:run` defaults to `--timing-mode custom`, so its daily limit and weekday sending window are honored. Use `--timing-mode auto` only when capacity-derived scheduling is intended.

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";
@@ -144,6 +145,18 @@ const AffiliateCampaignLaunchResponseSchema = z.object({
     extraction: z
         .object({
         provider: z.string().min(1),
+        runId: z.string().min(1).optional(),
+        resultCount: z.number().int().nonnegative().optional(),
+        deduplication: z
+            .object({
+            collectedCount: z.number().int().nonnegative(),
+            duplicateCount: z.number().int().nonnegative(),
+            withinBatchDuplicateCount: z.number().int().nonnegative(),
+            workspaceDuplicateCount: z.number().int().nonnegative(),
+            excludedSeedProfileCount: z.number().int().nonnegative(),
+            netNewCount: z.number().int().nonnegative(),
+        })
+            .optional(),
         monitorId: z.string().min(1).optional(),
         agentId: z.string().min(1).optional(),
         containerId: z.string().min(1).optional()
@@ -161,6 +174,21 @@ const AffiliateCampaignLaunchResponseSchema = z.object({
     previewUrl: z.string().nullable().optional(),
     next: z.string().optional()
 });
+const AffiliateAudienceVerificationSchema = z.object({
+    status: z.literal("ok"),
+    audience: z.object({
+        runId: z.string().uuid(),
+        status: z.enum(["launching", "running", "finished", "failed"]),
+        productDomain: z.string().min(1),
+        sourceType: z.string().min(1),
+        linkedInUrl: z.string().url(),
+        maxResults: z.number().int().positive(),
+        resultCount: z.number().int().nonnegative(),
+        provider: z.string().min(1).nullable(),
+        updatedAt: z.string().min(1),
+    }),
+    previewUrl: z.string().min(1),
+});
 const AffiliateCampaignLocalResultSchema = z
     .object({
     profileUrl: z.string().min(1),
@@ -599,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"
     },
     {
@@ -650,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"],
@@ -701,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",
@@ -6700,6 +6730,14 @@ async function launchAffiliateCampaignViaApp(session, payload) {
     }), AffiliateCampaignLaunchResponseSchema);
     return value;
 }
+async function verifyAffiliateCampaignViaApp(session, audienceRunId) {
+    const { value } = await fetchCliJson(session, (currentSession) => fetch(`${currentSession.apiBaseUrl}/api/cli/affiliate-campaigns/${encodeURIComponent(audienceRunId)}`, {
+        headers: {
+            Authorization: `Bearer ${currentSession.accessToken}`,
+        },
+    }), AffiliateAudienceVerificationSchema);
+    return value;
+}
 async function prepareAffiliateOutreachViaApp(session, payload) {
     const { value } = await fetchCliJson(session, (currentSession) => fetch(`${currentSession.apiBaseUrl}/api/cli/affiliate-outreach`, {
         method: "POST",
@@ -7935,7 +7973,7 @@ async function fetchLocalSalesNavigatorRequest(parsedRequest, retryOptions) {
                     retryDelayMs += await waitWithFullJitter(retryOptions.retryBaseDelayMs, retryOptions.retryMaxDelayMs, attempt);
                     continue;
                 }
-                throw new Error(`Sales Navigator request failed with HTTP ${response.status}: ${preview}`);
+                throw new LocalSalesNavigatorHttpError(response.status, text, `Sales Navigator request failed with HTTP ${response.status}: ${preview}`);
             }
             try {
                 return { body: JSON.parse(text), retryCount, retryDelayMs };
@@ -7945,7 +7983,8 @@ async function fetchLocalSalesNavigatorRequest(parsedRequest, retryOptions) {
             }
         }
         catch (error) {
-            if (error instanceof LocalSalesNavigatorRateLimitError) {
+            if (error instanceof LocalSalesNavigatorRateLimitError ||
+                error instanceof LocalSalesNavigatorHttpError) {
                 throw error;
             }
             if (attempt < retryOptions.maxRetries) {
@@ -14776,6 +14815,10 @@ async function runAffiliateLaunchCommand(options) {
             .max(accessibleResultLimit)
             .parse(options.maxResults);
     const session = await requireAuthSession();
+    const excludedProfileUrls = z
+        .array(z.string().url())
+        .max(100)
+        .parse(options.seedProfile ?? []);
     const isSalesNavigatorPeopleSearch = new URL(linkedInUrl).pathname.includes("/sales/search/people");
     let localResults;
     let localCollection;
@@ -14789,7 +14832,7 @@ async function runAffiliateLaunchCommand(options) {
         if (options.curlFile && browserRelayPort != null) {
             throw new Error("Use either --curl-file or --browser-relay-port, not both.");
         }
-        const parsedRequest = options.curlFile
+        let parsedRequest = options.curlFile
             ? parseSalesNavigatorCurlRequest(await readFile(path.resolve(String(options.curlFile)), "utf8"))
             : browserRelayPort != null
                 ? {
@@ -14805,7 +14848,7 @@ async function runAffiliateLaunchCommand(options) {
             : await createLocalAccountSearchBrowserRelay(browserRelayPort);
         let collected;
         try {
-            collected = await fetchAllLocalSalesNavigatorPeople(parsedRequest, {
+            const collect = async () => await fetchAllLocalSalesNavigatorPeople(parsedRequest, {
                 requestedProfiles: maxResults,
                 pageSize,
                 pageDelayMinMs,
@@ -14819,6 +14862,37 @@ async function runAffiliateLaunchCommand(options) {
                     ? (request) => browserRelay.request(request)
                     : undefined,
             });
+            try {
+                collected = await collect();
+            }
+            catch (error) {
+                const rejectedSession = error instanceof LocalSalesNavigatorHttpError &&
+                    (error.status === 401 || error.status === 403);
+                if (!rejectedSession ||
+                    options.curlFile ||
+                    browserRelay ||
+                    shouldDisableLinkedInDirectLookupAutodiscovery()) {
+                    throw error;
+                }
+                const extensionConfig = await readLocalLinkedInExtensionDirectLookupConfig();
+                if (!extensionConfig)
+                    throw error;
+                const extensionRequest = buildSalesNavigatorApiRequestFromSearchUrl(linkedInUrl, extensionConfig, pageSize);
+                if (extensionRequest.headers.cookie === parsedRequest.headers.cookie &&
+                    extensionRequest.headers["csrf-token"] === parsedRequest.headers["csrf-token"]) {
+                    throw error;
+                }
+                writeProgress("Stored Sales Navigator session was rejected; retrying with the latest extension-synced session.");
+                parsedRequest = extensionRequest;
+                collected = await collect();
+            }
+        }
+        catch (error) {
+            if (error instanceof LocalSalesNavigatorHttpError &&
+                (error.status === 401 || error.status === 403)) {
+                throw new Error("Sales Navigator rejected the available session. No audience was persisted. Refresh the Sales Navigator search in the signed-in browser, then rerun this command with a current --curl-file or --browser-relay-port. Workspace deduplication makes the retry safe.");
+            }
+            throw error;
         }
         finally {
             await browserRelay?.close();
@@ -14837,11 +14911,26 @@ async function runAffiliateLaunchCommand(options) {
         dryRun: Boolean(options.dryRun),
         localResults,
         localCollection,
+        ...(excludedProfileUrls.length > 0 ? { excludedProfileUrls } : {}),
     });
+    const runId = payload.extraction?.runId;
+    const verification = !options.dryRun && runId && z.string().uuid().safeParse(runId).success
+        ? await verifyAffiliateCampaignViaApp(session, runId)
+        : null;
+    if (verification) {
+        const expectedResultCount = payload.extraction?.resultCount;
+        if (verification.audience.status !== "finished") {
+            throw new Error(`Affiliate audience ${runId} was persisted but canonical status is ${verification.audience.status}, not finished.`);
+        }
+        if (expectedResultCount != null &&
+            verification.audience.resultCount !== expectedResultCount) {
+            throw new Error(`Affiliate audience ${runId} readback mismatch: created ${expectedResultCount}, stored ${verification.audience.resultCount}.`);
+        }
+    }
     if (options.out) {
-        await writeJsonFile(options.out, payload);
+        await writeJsonFile(options.out, { ...payload, verification });
     }
-    return { session, payload };
+    return { session, payload, verification };
 }
 function addAffiliateAudienceOptions(command) {
     return command
@@ -14850,6 +14939,7 @@ function addAffiliateAudienceOptions(command) {
         .option("--max-results <number>", "Maximum audience results (people searches: 2500; Connections of: 1000)")
         .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("--seed-profile <url>", "Exclude a known customer or seed profile; repeat for multiple profiles", collectStringOptionValue, [])
         .option("--page-size <number>", "Direct Sales Navigator page size", "100")
         .option("--page-delay-min-ms <number>", "Minimum delay between direct pages", "5000")
         .option("--page-delay-max-ms <number>", "Maximum delay between direct pages", "8000")
@@ -14915,12 +15005,13 @@ addAffiliateAudienceOptions(program
     .command("affiliate:launch")
     .description("Build an affiliate audience from an affiliate link and LinkedIn search URL."))
     .action(async (options) => {
-    const { payload } = await runAffiliateLaunchCommand(options);
-    printOutput(payload);
+    const { payload, verification } = await runAffiliateLaunchCommand(options);
+    printOutput({ ...payload, verification });
 });
 addAffiliateAudienceOptions(program
     .command("affiliate:run")
-    .description("Build an affiliate audience and prepare a reviewed Instantly campaign end to end."))
+    .alias("affiliate:grow")
+    .description("Collect, deduplicate, verify, and prepare a paused Instantly campaign end to end."))
     .option("--campaign-name <name>", "Optional Instantly campaign name")
     .option("--language <language>", "Sequence language", "English")
     .option("--steps <number>", "Exactly 3 sequence emails (fixed)", "3")
@@ -14938,6 +15029,13 @@ addAffiliateAudienceOptions(program
     if (options.dryRun) {
         printOutput({
             ...launched.payload,
+            verification: null,
+            journey: {
+                collection: "validated",
+                persistence: "not_requested",
+                outreach: "not_requested",
+                activation: "not_requested",
+            },
             outreach: {
                 status: "dry-run",
                 provider: "instantly",
@@ -14952,7 +15050,28 @@ addAffiliateAudienceOptions(program
         ? launched.payload.extraction.runId
         : null;
     if (!runId) {
-        throw new Error("The audience provider did not return a durable run id. End-to-end outreach requires a Sales Navigator people search.");
+        const deduplication = launched.payload.extraction?.deduplication;
+        if (deduplication?.netNewCount === 0) {
+            printOutput({
+                status: "ok",
+                audience: launched.payload,
+                verification: null,
+                journey: {
+                    collection: "complete",
+                    deduplication: "complete",
+                    persistence: "not_needed",
+                    outreach: "not_created",
+                    activation: "not_requested",
+                },
+                outreach: { status: "not_created", provider: "instantly" },
+                next: "Change the Sales Navigator cohort; every collected profile was already known or excluded.",
+            });
+            return;
+        }
+        throw new Error("The audience provider did not return a durable run id. End-to-end outreach requires a finished Sales Navigator people audience.");
+    }
+    if (!launched.verification) {
+        throw new Error(`Affiliate audience ${runId} was created but could not be independently verified. Outreach was not prepared.`);
     }
     const outreach = await prepareAffiliateOutreachViaApp(launched.session, {
         audienceRunId: z.string().uuid().parse(runId),
@@ -14964,6 +15083,16 @@ addAffiliateAudienceOptions(program
     printOutput({
         status: "ok",
         audience: launched.payload,
+        verification: launched.verification,
+        journey: {
+            collection: "complete",
+            deduplication: launched.payload.extraction?.deduplication
+                ? "complete"
+                : "not_reported",
+            persistence: "verified",
+            outreach: finalOutreach.status,
+            activation: finalOutreach.status === "active" ? "complete" : "not_requested",
+        },
         outreach: finalOutreach,
         next: finalOutreach.status === "ready"
             ? `Review the sequence, then run: salesprompter affiliate:activate ${runId}`
@@ -15223,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")