fullstackgtm 0.34.0 → 0.38.0

package/src/runReport.ts

@@ -0,0 +1,76 @@
+/**
+ * Opt-in CLI → hosted-app observability. When the user has paired the CLI
+ * (`login --via <url>` → broker token), each command fire-and-forgets a run
+ * record to the hosted app's `/api/cli/run`, authenticated by the broker token.
+ *
+ * Invariants: the CLI never requires web login; this does nothing when unpaired;
+ * it never throws and never changes the CLI's exit code or output. Reporting is
+ * pure added value for users who granted it.
+ */
+import { getCredential } from "./credentials.ts";
+
+type RunEvent = { ts: number; type: string; detail?: string };
+
+let counts: Record<string, unknown> | undefined;
+const events: RunEvent[] = [];
+
+/** A command annotates its headline metrics (merged). */
+export function reportCounts(values: Record<string, unknown>): void {
+  counts = { ...(counts ?? {}), ...values };
+}
+
+/** A command annotates a structured event (plan saved, meter charged, …). */
+export function reportEvent(type: string, detail?: string): void {
+  events.push({ ts: Date.now(), type, detail });
+}
+
+// Setup/inspection verbs aren't interesting as "runs" — skip the noise.
+const SKIP_COMMANDS = new Set([
+  "login",
+  "logout",
+  "doctor",
+  "help",
+  "profiles",
+  "--help",
+  "-h",
+  "--version",
+  "-v",
+]);
+
+/**
+ * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
+ * swallows every error. Call once per process from the entry point.
+ */
+export async function flushRunReport(
+  args: string[],
+  status: "success" | "partial" | "error",
+  startedAt: number,
+  error?: string,
+): Promise<void> {
+  const command = args[0];
+  if (!command || SKIP_COMMANDS.has(command)) return;
+  const broker = getCredential("broker");
+  if (!broker?.baseUrl || !broker.accessToken) return; // opt-in: only when paired
+
+  const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
+  const finishedAt = Date.now();
+  try {
+    await fetch(`${broker.baseUrl.replace(/\/+$/, "")}/api/cli/run`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        command: `${command}${sub}`,
+        status,
+        startedAt,
+        finishedAt,
+        durationMs: finishedAt - startedAt,
+        counts,
+        events: events.length ? events : undefined,
+        error,
+      }),
+      signal: AbortSignal.timeout(4000),
+    });
+  } catch {
+    // Observability is best-effort; never affect the CLI outcome.
+  }
+}

package/src/types.ts

@@ -43,11 +43,41 @@ export type PatchOperationType =
   | "link_record"
   | "archive_record"
   | "create_task"
+  // Create a NET-NEW record (a sourced lead). beforeValue is null (nothing
+  // existed); afterValue is a CreateRecordPayload. The connector re-resolves
+  // on matchKey at apply time (search is the source of truth; the plan-time
+  // snapshot can be stale) and creates only on a confirmed miss, so apply is
+  // resolve-first and never double-creates a record a concurrent writer added.
+  // Emitted only by `enrich acquire`, and metered against the acquire budget.
+  | "create_record"
   // Merge a duplicate group into a survivor. beforeValue is the group's
   // record ids; afterValue is the survivor id (requires_human_survivor_selection
   // until a human picks). IRREVERSIBLE on every provider that supports it.
   | "merge_records";
 
+/**
+ * The afterValue of a `create_record` operation. The connector re-resolves on
+ * `matchKey`/`matchValue` at apply time and creates only on a confirmed miss.
+ * `estCostUsd` is the acquire meter's per-record charge, recorded against the
+ * budget on a successful create.
+ */
+export type CreateRecordPayload = {
+  properties: Record<string, string>;
+  matchKey: string;
+  matchValue: string;
+  source: string;
+  estCostUsd?: number;
+  associateCompanyName?: string;
+  /**
+   * Owner to stamp on the new record (canonical owner id). The connector maps
+   * it to the CRM's owner property (HubSpot `hubspot_owner_id`) at create time
+   * so a lead is never born ownerless. Absent = leave unassigned.
+   */
+  ownerId?: string;
+  /** Audit label for how the owner was chosen (e.g. "fixed", "territory:0"). */
+  assignedBy?: string;
+};
+
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 
 /**
@@ -186,6 +216,8 @@ export type CanonicalContact = {
   email?: string;
   phone?: string;
   title?: string;
+  /** LinkedIn profile URL — the strongest cross-system identity key for dedup. */
+  linkedin?: string;
   ownerId?: string;
   lastActivityAt?: string;
   lastSyncAt?: string;