fullstackgtm 0.34.0 → 0.37.0

package/src/acquireMeter.ts

@@ -0,0 +1,186 @@
+/**
+ * The acquire meter — a persistent, windowed budget for net-new lead creation.
+ *
+ * `enrich acquire` proposes `create_record` operations; `apply` writes them.
+ * Both gate on this meter so a profile can never create more leads — or spend
+ * more on enrichment — than its declared budget, per day AND per month
+ * (whichever limit is hit first). The meter is the volume control; a human
+ * still approves the plan (the CLI never auto-writes). State is per-profile,
+ * stored under the credential home so one client's budget never bleeds into
+ * another's.
+ *
+ * Pure where it counts: window math and `remaining()` take an explicit `now`
+ * and operate on a passed-in state, so they are deterministic and testable.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { credentialsDir } from "./credentials.ts";
+
+/** Budget declared in enrich.config.json under `acquire.budget`. */
+export type AcquireBudget = {
+  records?: { perDay?: number; perMonth?: number };
+  spend?: { perDay?: number; perMonth?: number; currency?: string };
+};
+
+export type AcquireMeterState = {
+  /** UTC day bucket, YYYY-MM-DD. */
+  day: string;
+  /** UTC month bucket, YYYY-MM. */
+  month: string;
+  records: { day: number; month: number };
+  spendUsd: { day: number; month: number };
+};
+
+export type AcquireRemaining = {
+  /** Remaining headroom per window; null = no budget set for that dimension. */
+  records: { day: number | null; month: number | null };
+  spendUsd: { day: number | null; month: number | null };
+  /**
+   * The single number that matters: how many MORE records may be created right
+   * now, given every budget dimension and the per-record cost. null = unlimited
+   * (no budget constrains creation). 0 = budget exhausted.
+   */
+  maxRecords: number | null;
+};
+
+export function dayKey(now: Date): string {
+  return now.toISOString().slice(0, 10);
+}
+
+export function monthKey(now: Date): string {
+  return now.toISOString().slice(0, 7);
+}
+
+export function acquireMeterPath(baseDir?: string): string {
+  return join(baseDir ?? credentialsDir(), "acquire", "meter.json");
+}
+
+function emptyState(now: Date): AcquireMeterState {
+  return {
+    day: dayKey(now),
+    month: monthKey(now),
+    records: { day: 0, month: 0 },
+    spendUsd: { day: 0, month: 0 },
+  };
+}
+
+/**
+ * Roll the window counters forward: a new UTC day zeroes the day buckets, a
+ * new UTC month zeroes the month buckets. Returns a fresh object; never
+ * mutates the input.
+ */
+export function rollWindows(state: AcquireMeterState, now: Date): AcquireMeterState {
+  const today = dayKey(now);
+  const thisMonth = monthKey(now);
+  return {
+    day: today,
+    month: thisMonth,
+    records: {
+      day: state.day === today ? state.records.day : 0,
+      month: state.month === thisMonth ? state.records.month : 0,
+    },
+    spendUsd: {
+      day: state.day === today ? state.spendUsd.day : 0,
+      month: state.month === thisMonth ? state.spendUsd.month : 0,
+    },
+  };
+}
+
+/** Load the meter from disk, rolling stale windows forward. Missing = empty. */
+export function loadMeter(now: Date, baseDir?: string): AcquireMeterState {
+  let raw: string;
+  try {
+    raw = readFileSync(acquireMeterPath(baseDir), "utf8");
+  } catch {
+    return emptyState(now);
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<AcquireMeterState>;
+    const state: AcquireMeterState = {
+      day: typeof parsed.day === "string" ? parsed.day : dayKey(now),
+      month: typeof parsed.month === "string" ? parsed.month : monthKey(now),
+      records: {
+        day: Number(parsed.records?.day) || 0,
+        month: Number(parsed.records?.month) || 0,
+      },
+      spendUsd: {
+        day: Number(parsed.spendUsd?.day) || 0,
+        month: Number(parsed.spendUsd?.month) || 0,
+      },
+    };
+    return rollWindows(state, now);
+  } catch {
+    return emptyState(now);
+  }
+}
+
+export function saveMeter(state: AcquireMeterState, baseDir?: string): void {
+  const path = acquireMeterPath(baseDir);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function headroom(limit: number | undefined, used: number): number | null {
+  if (limit === undefined) return null;
+  return Math.max(0, limit - used);
+}
+
+/**
+ * Compute remaining headroom and the max additional records creatable now.
+ * `costPerRecord` (USD) converts the spend budget into a record ceiling; when
+ * it is 0 the spend budget cannot constrain record count.
+ */
+export function remaining(
+  state: AcquireMeterState,
+  budget: AcquireBudget | undefined,
+  costPerRecord: number,
+  now: Date,
+): AcquireRemaining {
+  const rolled = rollWindows(state, now);
+  const records = {
+    day: headroom(budget?.records?.perDay, rolled.records.day),
+    month: headroom(budget?.records?.perMonth, rolled.records.month),
+  };
+  const spendUsd = {
+    day: headroom(budget?.spend?.perDay, rolled.spendUsd.day),
+    month: headroom(budget?.spend?.perMonth, rolled.spendUsd.month),
+  };
+
+  const ceilings: number[] = [];
+  if (records.day !== null) ceilings.push(records.day);
+  if (records.month !== null) ceilings.push(records.month);
+  if (costPerRecord > 0) {
+    if (spendUsd.day !== null) ceilings.push(Math.floor(spendUsd.day / costPerRecord));
+    if (spendUsd.month !== null) ceilings.push(Math.floor(spendUsd.month / costPerRecord));
+  }
+  const maxRecords = ceilings.length === 0 ? null : Math.max(0, Math.min(...ceilings));
+  return { records, spendUsd, maxRecords };
+}
+
+/**
+ * Record a successful batch of creates against the budget and persist.
+ * Returns the updated state. Call AFTER the writes land, so a failed apply
+ * never charges the meter.
+ */
+export function recordConsumption(
+  now: Date,
+  recordsCreated: number,
+  spendUsd: number,
+  baseDir?: string,
+): AcquireMeterState {
+  const state = loadMeter(now, baseDir);
+  const next: AcquireMeterState = {
+    day: state.day,
+    month: state.month,
+    records: {
+      day: state.records.day + recordsCreated,
+      month: state.records.month + recordsCreated,
+    },
+    spendUsd: {
+      day: state.spendUsd.day + spendUsd,
+      month: state.spendUsd.month + spendUsd,
+    },
+  };
+  saveMeter(next, baseDir);
+  return next;
+}

package/src/acquireSeen.ts

@@ -0,0 +1,57 @@
+/**
+ * The acquire "seen" cache — cross-run memory of prospects already processed,
+ * so re-running the same ICP doesn't re-pay the (expensive) email-resolution
+ * step for people we resolved last time. Keyed by stable prospect identity
+ * (LinkedIn URL, name+domain, email); a hit on ANY key means "skip before
+ * paying". Per-profile, stored under the credential home.
+ *
+ * Distinct from the meter (spend budget) and from the live-CRM dedup (the
+ * snapshot match + apply-time resolve-first): this avoids RE-spending across
+ * runs; those avoid double-creating within/against the CRM.
+ *
+ * Zero deps. Stored as { key: lastSeenISO } so the cache can be pruned by age.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { credentialsDir } from "./credentials.ts";
+
+type SeenStore = Record<string, string>;
+
+/** Keep the newest N keys; bounds the file for very large/long-running fills. */
+const SEEN_CAP = 50_000;
+
+export function acquireSeenPath(baseDir?: string): string {
+  return join(baseDir ?? credentialsDir(), "acquire", "seen.json");
+}
+
+/** Load the set of seen keys (empty if none/corrupt). */
+export function loadSeen(baseDir?: string): Set<string> {
+  try {
+    const store = JSON.parse(readFileSync(acquireSeenPath(baseDir), "utf8")) as SeenStore;
+    return new Set(Object.keys(store));
+  } catch {
+    return new Set();
+  }
+}
+
+/** Merge keys into the cache with a `now` timestamp, prune to cap, persist. */
+export function recordSeen(keys: string[], now: Date, baseDir?: string): void {
+  if (keys.length === 0) return;
+  let store: SeenStore = {};
+  try {
+    store = JSON.parse(readFileSync(acquireSeenPath(baseDir), "utf8")) as SeenStore;
+  } catch {
+    store = {};
+  }
+  const iso = now.toISOString();
+  for (const key of keys) store[key] = iso;
+
+  let entries = Object.entries(store);
+  if (entries.length > SEEN_CAP) {
+    entries = entries.sort((a, b) => (a[1] < b[1] ? 1 : -1)).slice(0, SEEN_CAP);
+    store = Object.fromEntries(entries);
+  }
+  const path = acquireSeenPath(baseDir);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(store)}\n`, "utf8");
+}