salesprompter-cli 0.1.19 → 0.1.20

package/dist/salesnav-backfill.js

@@ -0,0 +1,710 @@
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { BigQuery } from "@google-cloud/bigquery";
+import { createClient } from "@supabase/supabase-js";
+const DEFAULT_WINDOW_SIZE = 100_000;
+const DEFAULT_PAGE_SIZE = 500;
+const DEFAULT_UPSERT_BATCH_SIZE = 50;
+const DEFAULT_MIN_UPSERT_BATCH_SIZE = 10;
+const DEFAULT_MAX_UPSERT_RETRIES = 8;
+const DEFAULT_RETRY_DELAY_MS = 1_000;
+const DEFAULT_MAX_COUNT_RETRIES = 5;
+const DEFAULT_COUNT_RETRY_DELAY_MS = 5_000;
+const HISTORICAL_BACKFILL_SOURCE_QUERY_URL = "bigquery://SalesPrompter/salesnav-people";
+const HISTORICAL_BACKFILL_SLICE_PRESET = "historical-bigquery-salesnav-backfill";
+const HISTORICAL_BACKFILL_AGENT_ID = "historical-bigquery-backfill";
+function toFiniteInteger(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length === 0) {
+            return null;
+        }
+        const parsed = Number(trimmed);
+        return Number.isFinite(parsed) ? Math.trunc(parsed) : null;
+    }
+    return null;
+}
+export function resolveSalesNavigatorHistoricalBackfillConfig(env = process.env) {
+    const supabaseUrl = env.SALESPROMPTER_SUPABASE_URL?.trim() || env.NEXT_PUBLIC_SUPABASE_URL?.trim() || "";
+    const supabaseServiceRoleKey = env.SUPABASE_SERVICE_ROLE_KEY?.trim() || "";
+    const rawServiceAccountKey = env.GOOGLE_SERVICE_ACCOUNT_KEY?.trim() || "";
+    const bigQueryProjectId = env.BIGQUERY_PROJECT_ID?.trim() || "";
+    const missing = [];
+    if (supabaseUrl.length === 0) {
+        missing.push("SALESPROMPTER_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_URL");
+    }
+    if (supabaseServiceRoleKey.length === 0) {
+        missing.push("SUPABASE_SERVICE_ROLE_KEY");
+    }
+    if (rawServiceAccountKey.length === 0) {
+        missing.push("GOOGLE_SERVICE_ACCOUNT_KEY");
+    }
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variables for historical Sales Navigator backfill: ${missing.join(", ")}`);
+    }
+    let bigQueryCredentials;
+    try {
+        bigQueryCredentials = JSON.parse(rawServiceAccountKey.replace(/\\n$/, ""));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`GOOGLE_SERVICE_ACCOUNT_KEY is not valid JSON: ${message}`);
+    }
+    const projectIdFromCredentials = typeof bigQueryCredentials.project_id === "string"
+        ? bigQueryCredentials.project_id
+        : "";
+    const resolvedProjectId = bigQueryProjectId || projectIdFromCredentials;
+    if (resolvedProjectId.length === 0) {
+        throw new Error("BIGQUERY_PROJECT_ID is required when GOOGLE_SERVICE_ACCOUNT_KEY does not contain project_id.");
+    }
+    return {
+        supabaseUrl,
+        supabaseServiceRoleKey,
+        bigQueryProjectId: resolvedProjectId,
+        bigQueryCredentials
+    };
+}
+export function resolveSalesNavigatorHistoricalBackfillOrgId(options) {
+    const explicitOrgId = options.explicitOrgId?.trim();
+    if (explicitOrgId) {
+        return explicitOrgId;
+    }
+    const envOrgId = options.env?.SALESPROMPTER_ORG_ID?.trim();
+    if (envOrgId) {
+        return envOrgId;
+    }
+    const sessionOrgId = options.sessionOrgId?.trim();
+    if (sessionOrgId) {
+        return sessionOrgId;
+    }
+    throw new Error("Sales Navigator historical backfill requires --org-id, SALESPROMPTER_ORG_ID, or an authenticated CLI session with an active org.");
+}
+export function buildSalesNavigatorHistoricalBackfillPlan(options) {
+    const currentCount = options.currentCount;
+    const remainingToTarget = currentCount === null ? null : Math.max(0, options.targetCount - currentCount);
+    const windows = [];
+    for (let index = 0; index < options.maxWindows; index += 1) {
+        windows.push({
+            index,
+            offset: options.startOffset + index * options.windowSize,
+            limit: options.windowSize
+        });
+    }
+    return {
+        targetCount: options.targetCount,
+        currentCount,
+        startOffset: options.startOffset,
+        windowSize: options.windowSize,
+        maxWindows: options.maxWindows,
+        remainingToTarget,
+        windows
+    };
+}
+export function inferSalesNavigatorHistoricalBackfillResumeState(options) {
+    const latestByOffset = new Map();
+    for (const row of options.rows) {
+        const rawPayload = row.raw_payload ?? {};
+        if (rawPayload.scope !== options.scope) {
+            continue;
+        }
+        const offset = toFiniteInteger(rawPayload.offset);
+        const limit = toFiniteInteger(rawPayload.limit);
+        if (offset === null || limit !== options.windowSize || offset < options.fallbackOffset) {
+            continue;
+        }
+        const parsedFinishedAt = row.finished_at ? Date.parse(row.finished_at) : Number.NaN;
+        const finishedAtMs = Number.isFinite(parsedFinishedAt)
+            ? parsedFinishedAt
+            : Number.NEGATIVE_INFINITY;
+        const latestEntry = latestByOffset.get(offset);
+        if (latestEntry && latestEntry.finishedAtMs > finishedAtMs) {
+            continue;
+        }
+        const isSuccessful = row.status === "finished" && (row.result_classification ?? "success") === "success";
+        latestByOffset.set(offset, {
+            status: isSuccessful ? "success" : "failed",
+            finishedAtMs
+        });
+    }
+    if (latestByOffset.size === 0) {
+        return {
+            startOffset: options.fallbackOffset,
+            resumedFromHistory: false,
+            matchedHistoryRows: 0,
+            reason: "fallback"
+        };
+    }
+    const offsets = [...latestByOffset.keys()].sort((left, right) => left - right);
+    const highestOffset = offsets[offsets.length - 1] ?? options.fallbackOffset;
+    for (let currentOffset = options.fallbackOffset; currentOffset <= highestOffset; currentOffset += options.windowSize) {
+        const entry = latestByOffset.get(currentOffset);
+        if (!entry) {
+            return {
+                startOffset: currentOffset,
+                resumedFromHistory: true,
+                matchedHistoryRows: latestByOffset.size,
+                reason: "fill-gap"
+            };
+        }
+        if (entry.status !== "success") {
+            return {
+                startOffset: currentOffset,
+                resumedFromHistory: true,
+                matchedHistoryRows: latestByOffset.size,
+                reason: "retry-failed-window"
+            };
+        }
+    }
+    return {
+        startOffset: highestOffset + options.windowSize,
+        resumedFromHistory: true,
+        matchedHistoryRows: latestByOffset.size,
+        reason: "next-unprocessed-window"
+    };
+}
+export async function resolveSalesNavigatorHistoricalBackfillResumeState(options) {
+    const rows = [];
+    const pageSize = 1000;
+    for (let pageIndex = 0; pageIndex < 20; pageIndex += 1) {
+        const from = pageIndex * pageSize;
+        const to = from + pageSize - 1;
+        const result = await options.supabase
+            .from("linkedin_sales_nav_export_runs")
+            .select("status,result_classification,finished_at,raw_payload")
+            .eq("org_id", options.orgId)
+            .eq("slice_preset", HISTORICAL_BACKFILL_SLICE_PRESET)
+            .order("finished_at", { ascending: true })
+            .range(from, to);
+        if (result.error) {
+            throw new Error(`Failed to load historical Sales Navigator backfill runs: ${result.error.message}`);
+        }
+        const pageRows = Array.isArray(result.data) ? result.data : [];
+        rows.push(...pageRows);
+        if (pageRows.length < pageSize) {
+            break;
+        }
+    }
+    return inferSalesNavigatorHistoricalBackfillResumeState({
+        rows,
+        scope: options.scope,
+        windowSize: options.windowSize,
+        fallbackOffset: options.fallbackOffset
+    });
+}
+export function buildSalesNavigatorHistoricalBackfillQuery(limit, offset, scope) {
+    const limitClause = `\nLIMIT ${Math.trunc(limit)}`;
+    const offsetClause = offset > 0 ? `\nOFFSET ${Math.trunc(offset)}` : "";
+    const leadListFilterClause = scope === "hr-function-included"
+        ? `
+    AND REGEXP_CONTAINS(LOWER(CAST(query AS STRING)), r'type%3afunction[^)]*id%3a12[^)]*selectiontype%3aincluded')
+    AND NOT REGEXP_CONTAINS(LOWER(CAST(query AS STRING)), r'id%3a12[^)]*selectiontype%3aexcluded')`
+        : "";
+    return `WITH hr_leadlists AS (
+  SELECT
+    CAST(leadListId AS STRING) AS leadListId,
+    CAST(query AS STRING) AS leadListQuery,
+    CAST(leadList_container_ts AS STRING) AS leadListContainerTs
+  FROM \`icpidentifier.SalesPrompter.leadLists_raw\`
+  WHERE query IS NOT NULL
+    AND LOWER(CAST(query AS STRING)) LIKE '%/sales/search/people%'${leadListFilterClause}
+  QUALIFY ROW_NUMBER() OVER (
+    PARTITION BY CAST(leadListId AS STRING)
+    ORDER BY leadList_container_ts DESC
+  ) = 1
+), contacts AS (
+  SELECT
+    CAST(leadListId AS STRING) AS leadListId,
+    CAST(contactId AS STRING) AS contactId,
+    CAST(companyId AS STRING) AS companyId,
+    CAST(firstName AS STRING) AS firstName,
+    CAST(lastName AS STRING) AS lastName,
+    CAST(jobTitle AS STRING) AS jobTitle,
+    CAST(contact_companyName AS STRING) AS contactCompanyName,
+    CAST(contact_location AS STRING) AS contactLocation,
+    CAST(contact_companyLocation AS STRING) AS contactCompanyLocation,
+    CAST(contact_summary AS STRING) AS contactSummary,
+    CAST(contact_titleDescription AS STRING) AS contactTitleDescription,
+    CAST(tenureAtCompany AS STRING) AS tenureAtCompany,
+    CAST(tenureAtPosition AS STRING) AS tenureAtPosition,
+    CAST(contact_ts AS STRING) AS contactTs,
+    CAST(isPremium AS STRING) AS isPremium,
+    CAST(isOpenLink AS STRING) AS isOpenLink
+  FROM \`icpidentifier.SalesPrompter.linkedin_contacts\`
+  WHERE contactId IS NOT NULL
+), companies AS (
+  SELECT
+    CAST(id AS STRING) AS companyId,
+    CAST(handle AS STRING) AS handle,
+    CAST(name AS STRING) AS name,
+    CAST(companySize AS STRING) AS companySize,
+    CAST(countryCode AS STRING) AS countryCode,
+    CAST(headquarters AS STRING) AS headquarters,
+    CAST(domain AS STRING) AS domain,
+    CAST(domain_linkedin AS STRING) AS domainLinkedin,
+    CAST(website_linkedin AS STRING) AS websiteLinkedin,
+    CAST(industry AS STRING) AS industry,
+    CAST(timestamp AS STRING) AS companyTs
+  FROM \`icpidentifier.SalesPrompter.linkedin_companies\`
+)
+SELECT
+  contacts.contactId,
+  contacts.companyId,
+  contacts.firstName,
+  contacts.lastName,
+  contacts.jobTitle,
+  contacts.contactCompanyName,
+  contacts.contactLocation,
+  contacts.contactCompanyLocation,
+  contacts.contactSummary,
+  contacts.contactTitleDescription,
+  contacts.tenureAtCompany,
+  contacts.tenureAtPosition,
+  contacts.contactTs,
+  contacts.isPremium,
+  contacts.isOpenLink,
+  hr_leadlists.leadListId,
+  hr_leadlists.leadListQuery,
+  hr_leadlists.leadListContainerTs,
+  companies.handle AS companyHandle,
+  companies.name AS companyName,
+  companies.companySize,
+  companies.countryCode,
+  companies.headquarters,
+  companies.domain,
+  companies.domainLinkedin,
+  companies.websiteLinkedin,
+  companies.industry,
+  companies.companyTs
+FROM contacts
+JOIN hr_leadlists USING (leadListId)
+LEFT JOIN companies USING (companyId)
+QUALIFY ROW_NUMBER() OVER (
+  PARTITION BY contacts.contactId
+  ORDER BY contacts.contactTs DESC, hr_leadlists.leadListContainerTs DESC, companies.companyTs DESC
+) = 1
+ORDER BY contacts.contactId${limitClause}${offsetClause}`;
+}
+function sanitizeText(value) {
+    const input = value.replace(/\u0000/g, "");
+    let output = "";
+    for (let index = 0; index < input.length; index += 1) {
+        const code = input.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = input.charCodeAt(index + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                output += input[index] + input[index + 1];
+                index += 1;
+            }
+            else {
+                output += "�";
+            }
+            continue;
+        }
+        if (code >= 0xdc00 && code <= 0xdfff) {
+            output += "�";
+            continue;
+        }
+        output += input[index];
+    }
+    return output.normalize("NFC");
+}
+function sanitizeValue(value) {
+    if (typeof value === "string") {
+        return sanitizeText(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeValue(item));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, sanitizeValue(entry)]));
+    }
+    return value;
+}
+function toNullableString(value) {
+    if (value == null) {
+        return null;
+    }
+    const trimmed = sanitizeText(String(value)).trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function toNullableBoolean(value) {
+    if (value == null) {
+        return null;
+    }
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === "true") {
+        return true;
+    }
+    if (normalized === "false") {
+        return false;
+    }
+    return null;
+}
+function toNullableIsoTimestamp(value) {
+    const stringValue = toNullableString(value);
+    if (!stringValue) {
+        return null;
+    }
+    const timestamp = Date.parse(stringValue);
+    return Number.isNaN(timestamp) ? null : new Date(timestamp).toISOString();
+}
+function buildSalesNavigatorProfileUrl(contactId) {
+    return `https://www.linkedin.com/sales/lead/${contactId}`;
+}
+function mapHistoricalContactRowToPerson(options) {
+    const contactId = toNullableString(options.row.contactId);
+    if (!contactId) {
+        throw new Error("Historical backfill row is missing contactId");
+    }
+    const companyId = toNullableString(options.row.companyId);
+    const firstName = toNullableString(options.row.firstName);
+    const lastName = toNullableString(options.row.lastName);
+    const companyName = toNullableString(options.row.companyName) ?? toNullableString(options.row.contactCompanyName);
+    return {
+        org_id: options.orgId,
+        run_id: null,
+        phantom_container_id: options.containerId,
+        sales_nav_profile_url: buildSalesNavigatorProfileUrl(contactId),
+        linkedin_profile_url: null,
+        default_profile_url: null,
+        full_name: [firstName, lastName].filter(Boolean).join(" ") || null,
+        first_name: firstName,
+        last_name: lastName,
+        company_name: companyName,
+        company_id: companyId,
+        company_url: companyId ? `https://www.linkedin.com/company/${companyId}` : null,
+        regular_company_url: toNullableString(options.row.websiteLinkedin),
+        title: toNullableString(options.row.jobTitle),
+        industry: toNullableString(options.row.industry),
+        summary: toNullableString(options.row.contactSummary),
+        title_description: toNullableString(options.row.contactTitleDescription),
+        location: toNullableString(options.row.contactLocation),
+        company_location: toNullableString(options.row.contactCompanyLocation),
+        duration_in_role: toNullableString(options.row.tenureAtPosition),
+        duration_in_company: toNullableString(options.row.tenureAtCompany),
+        connection_degree: null,
+        shared_connections_count: null,
+        profile_image_url: null,
+        vmid: null,
+        search_query: toNullableString(options.row.leadListQuery),
+        search_account_profile_id: null,
+        search_account_profile_name: null,
+        scraped_at: toNullableIsoTimestamp(options.row.contactTs) ?? new Date().toISOString(),
+        is_premium: toNullableBoolean(options.row.isPremium),
+        is_open_link: toNullableBoolean(options.row.isOpenLink),
+        raw_payload: sanitizeValue(options.row)
+    };
+}
+function isRetryableUpsertError(error) {
+    const message = error.message.toLowerCase();
+    return (message.includes("statement timeout") ||
+        message.includes("connection terminated") ||
+        message.includes("connection closed") ||
+        message.includes("fetch failed") ||
+        message.includes("network") ||
+        message.includes("temporarily unavailable") ||
+        message.includes("rate limit"));
+}
+async function upsertHistoricalPeopleBatch(supabase, batch) {
+    const result = await supabase.from("linkedin_sales_nav_people").upsert(batch, {
+        onConflict: "org_id,sales_nav_profile_url",
+        ignoreDuplicates: false
+    });
+    if (result.error) {
+        throw new Error(`Failed to upsert historical backfill batch: ${result.error.message}`);
+    }
+}
+async function upsertHistoricalPeopleBatchWithRetry(supabase, batch, options, attempt = 0) {
+    try {
+        await upsertHistoricalPeopleBatch(supabase, batch);
+        return;
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !isRetryableUpsertError(error)) {
+            throw error;
+        }
+        if (batch.length > options.minUpsertBatchSize) {
+            const midpoint = Math.ceil(batch.length / 2);
+            await upsertHistoricalPeopleBatchWithRetry(supabase, batch.slice(0, midpoint), options, 0);
+            await upsertHistoricalPeopleBatchWithRetry(supabase, batch.slice(midpoint), options, 0);
+            return;
+        }
+        if (attempt >= options.maxUpsertRetries) {
+            throw error;
+        }
+        await delay(options.retryDelayMs * 2 ** attempt);
+        await upsertHistoricalPeopleBatchWithRetry(supabase, batch, options, attempt + 1);
+    }
+}
+async function queryExactSalesNavigatorPeopleCount(supabase, orgId) {
+    let lastMessage = "unknown count error";
+    for (let attempt = 0; attempt < DEFAULT_MAX_COUNT_RETRIES; attempt += 1) {
+        const result = await supabase
+            .from("linkedin_sales_nav_people")
+            .select("*", { head: true, count: "exact" })
+            .eq("org_id", orgId);
+        if (!result.error && Number.isFinite(result.count)) {
+            return result.count;
+        }
+        lastMessage = result.error?.message || lastMessage;
+        await delay(DEFAULT_COUNT_RETRY_DELAY_MS);
+    }
+    throw new Error(`Failed to read exact linkedin_sales_nav_people count: ${lastMessage}`);
+}
+async function insertHistoricalBackfillRun(supabase, row) {
+    const result = await supabase.from("linkedin_sales_nav_export_runs").upsert(row, {
+        onConflict: "org_id,phantom_container_id",
+        ignoreDuplicates: false
+    });
+    if (result.error) {
+        throw new Error(`Failed to record historical backfill run: ${result.error.message}`);
+    }
+}
+async function runSalesNavigatorHistoricalBackfillWindow(options) {
+    options.onProgress?.({
+        type: "window-start",
+        windowIndex: options.windowIndex,
+        offset: options.offset,
+        limit: options.limit,
+        containerId: options.containerId
+    });
+    const query = buildSalesNavigatorHistoricalBackfillQuery(options.limit, options.offset, options.scope);
+    const [queryJob] = await options.bigQuery.createQueryJob({
+        query,
+        useLegacySql: false
+    });
+    await queryJob.promise();
+    const [firstRows, nextQuery, response] = await queryJob.getQueryResults({
+        maxResults: options.pageSize
+    });
+    const totalResults = Number(response?.totalRows ?? firstRows.length);
+    let processed = 0;
+    let pageToken = nextQuery?.pageToken ?? null;
+    const processRows = async (rows) => {
+        if (rows.length === 0) {
+            return;
+        }
+        for (let start = 0; start < rows.length; start += options.upsertBatchSize) {
+            const batch = rows
+                .slice(start, start + options.upsertBatchSize)
+                .map((row) => mapHistoricalContactRowToPerson({
+                orgId: options.orgId,
+                containerId: options.containerId,
+                row
+            }));
+            await upsertHistoricalPeopleBatchWithRetry(options.supabase, batch, {
+                minUpsertBatchSize: options.minUpsertBatchSize,
+                maxUpsertRetries: options.maxUpsertRetries,
+                retryDelayMs: options.retryDelayMs
+            });
+            processed += batch.length;
+            if (processed % 5000 === 0 || processed === totalResults) {
+                options.onProgress?.({
+                    type: "window-progress",
+                    windowIndex: options.windowIndex,
+                    offset: options.offset,
+                    limit: options.limit,
+                    processed,
+                    totalResults,
+                    percent: Number(((processed / Math.max(totalResults, 1)) * 100).toFixed(2)),
+                    containerId: options.containerId
+                });
+            }
+        }
+    };
+    await processRows(firstRows ?? []);
+    while (pageToken) {
+        const [rows, next, apiResponse] = await queryJob.getQueryResults({
+            maxResults: options.pageSize,
+            pageToken
+        });
+        pageToken = next?.pageToken ?? null;
+        await processRows(rows ?? []);
+        if (!pageToken && apiResponse?.pageToken) {
+            pageToken = apiResponse.pageToken;
+        }
+    }
+    return { processed, totalResults };
+}
+export async function ensureSalesNavigatorPeopleCount(options) {
+    const supabase = createClient(options.config.supabaseUrl, options.config.supabaseServiceRoleKey, {
+        auth: { persistSession: false }
+    });
+    const bigQuery = new BigQuery({
+        projectId: options.config.bigQueryProjectId,
+        credentials: options.config.bigQueryCredentials
+    });
+    const initialCount = await queryExactSalesNavigatorPeopleCount(supabase, options.orgId);
+    const windows = [];
+    if (initialCount >= options.targetCount) {
+        return {
+            status: "ok",
+            orgId: options.orgId,
+            scope: options.scope,
+            targetCount: options.targetCount,
+            initialCount,
+            currentCount: initialCount,
+            resumedFromHistory: Boolean(options.resumedFromHistory),
+            startOffset: options.startOffset,
+            nextOffset: options.startOffset,
+            exhausted: false,
+            completedWindows: 0,
+            windows
+        };
+    }
+    let currentCount = initialCount;
+    let exhausted = false;
+    let nextOffset = options.startOffset;
+    const runSeed = `${Date.now()}-${randomUUID().slice(0, 8)}`;
+    for (let windowIndex = 0; windowIndex < options.maxWindows; windowIndex += 1) {
+        const countBefore = currentCount;
+        const containerId = `salesprompter-cli-salesnav-backfill-${runSeed}-window-${windowIndex + 1}-offset-${nextOffset}`;
+        const sourceQueryUrl = `${HISTORICAL_BACKFILL_SOURCE_QUERY_URL}?scope=${encodeURIComponent(options.scope)}&offset=${nextOffset}&limit=${options.windowSize}`;
+        const slicedQueryUrl = sourceQueryUrl;
+        try {
+            const windowResult = await runSalesNavigatorHistoricalBackfillWindow({
+                bigQuery,
+                supabase,
+                orgId: options.orgId,
+                scope: options.scope,
+                offset: nextOffset,
+                limit: options.windowSize,
+                pageSize: options.pageSize ?? DEFAULT_PAGE_SIZE,
+                upsertBatchSize: options.upsertBatchSize ?? DEFAULT_UPSERT_BATCH_SIZE,
+                minUpsertBatchSize: options.minUpsertBatchSize ?? DEFAULT_MIN_UPSERT_BATCH_SIZE,
+                maxUpsertRetries: options.maxUpsertRetries ?? DEFAULT_MAX_UPSERT_RETRIES,
+                retryDelayMs: options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS,
+                containerId,
+                onProgress: options.onProgress,
+                windowIndex
+            });
+            currentCount = await queryExactSalesNavigatorPeopleCount(supabase, options.orgId);
+            const countDelta = currentCount - countBefore;
+            windows.push({
+                containerId,
+                offset: nextOffset,
+                limit: options.windowSize,
+                processed: windowResult.processed,
+                totalResults: windowResult.totalResults,
+                countBefore,
+                countAfter: currentCount,
+                countDelta
+            });
+            await insertHistoricalBackfillRun(supabase, {
+                org_id: options.orgId,
+                source_query_url: sourceQueryUrl,
+                sliced_query_url: slicedQueryUrl,
+                slice_preset: HISTORICAL_BACKFILL_SLICE_PRESET,
+                applied_filters: options.scope === "hr-function-included"
+                    ? [
+                        {
+                            type: "FUNCTION",
+                            values: [{ id: "12", text: "Human Resources", selectionType: "INCLUDED" }]
+                        }
+                    ]
+                    : [],
+                max_results_per_search: 2500,
+                number_of_profiles: 2500,
+                phantom_agent_id: HISTORICAL_BACKFILL_AGENT_ID,
+                phantom_container_id: containerId,
+                phantom_result_json_url: null,
+                phantom_result_csv_url: null,
+                phantom_total_results: windowResult.totalResults,
+                phantom_output: `Historical BigQuery ${options.scope} backfill complete (${windowResult.processed}/${windowResult.totalResults})`,
+                exported_results: windowResult.processed,
+                status: "finished",
+                result_classification: "success",
+                error_message: null,
+                finished_at: new Date().toISOString(),
+                raw_payload: {
+                    source: "bigquery",
+                    scope: options.scope,
+                    offset: nextOffset,
+                    limit: options.windowSize,
+                    countDelta
+                }
+            });
+            options.onProgress?.({
+                type: "window-complete",
+                windowIndex,
+                offset: nextOffset,
+                limit: options.windowSize,
+                processed: windowResult.processed,
+                totalResults: windowResult.totalResults,
+                countBefore,
+                countAfter: currentCount,
+                countDelta,
+                containerId
+            });
+            if (windowResult.processed < options.windowSize) {
+                exhausted = true;
+            }
+            if (currentCount >= options.targetCount || exhausted) {
+                break;
+            }
+            nextOffset += options.windowSize;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await insertHistoricalBackfillRun(supabase, {
+                org_id: options.orgId,
+                source_query_url: sourceQueryUrl,
+                sliced_query_url: slicedQueryUrl,
+                slice_preset: HISTORICAL_BACKFILL_SLICE_PRESET,
+                applied_filters: options.scope === "hr-function-included"
+                    ? [
+                        {
+                            type: "FUNCTION",
+                            values: [{ id: "12", text: "Human Resources", selectionType: "INCLUDED" }]
+                        }
+                    ]
+                    : [],
+                max_results_per_search: 2500,
+                number_of_profiles: 2500,
+                phantom_agent_id: HISTORICAL_BACKFILL_AGENT_ID,
+                phantom_container_id: containerId,
+                phantom_result_json_url: null,
+                phantom_result_csv_url: null,
+                phantom_total_results: 0,
+                phantom_output: `Historical BigQuery ${options.scope} backfill failed`,
+                exported_results: 0,
+                status: "failed",
+                result_classification: "transient_failure",
+                error_message: message,
+                finished_at: new Date().toISOString(),
+                raw_payload: {
+                    source: "bigquery",
+                    scope: options.scope,
+                    offset: nextOffset,
+                    limit: options.windowSize
+                }
+            });
+            throw error;
+        }
+    }
+    return {
+        status: currentCount >= options.targetCount ? "ok" : "incomplete",
+        orgId: options.orgId,
+        scope: options.scope,
+        targetCount: options.targetCount,
+        initialCount,
+        currentCount,
+        resumedFromHistory: Boolean(options.resumedFromHistory),
+        startOffset: options.startOffset,
+        nextOffset,
+        exhausted,
+        completedWindows: windows.length,
+        windows
+    };
+}
+export const salesNavigatorHistoricalBackfillDefaults = {
+    windowSize: DEFAULT_WINDOW_SIZE,
+    pageSize: DEFAULT_PAGE_SIZE,
+    upsertBatchSize: DEFAULT_UPSERT_BATCH_SIZE,
+    minUpsertBatchSize: DEFAULT_MIN_UPSERT_BATCH_SIZE,
+    maxUpsertRetries: DEFAULT_MAX_UPSERT_RETRIES,
+    retryDelayMs: DEFAULT_RETRY_DELAY_MS
+};