fullstackgtm 0.41.0 → 0.43.0

package/src/calls.ts

@@ -369,6 +369,15 @@ export type CallDealSuggestion = {
   dealName?: string;
   accountId?: string;
   accountName?: string;
+  /**
+   * HOW the deal's account was matched — `account_domain` (the company-wide,
+   * reliable signal) vs `contact_email` (a specific person, possibly stale) vs
+   * `both`. An agent needs this to weight the match; the bare confidence hides it.
+   */
+  resolvedVia?: "account_domain" | "contact_email" | "both";
+  /** The attendee contacts that matched (the email path), so the contact↔account
+   *  hop is visible, not just the resolved account. */
+  matchedContacts?: { id: string; email?: string; accountId?: string }[];
   confidence: "high" | "low" | "none";
   reason: string;
 };
@@ -393,17 +402,27 @@ export function suggestCallDeal(
   }
 
   const accountIds = new Set<string>();
+  let viaDomain = false;
+  let viaEmail = false;
+  const matchedContacts: { id: string; email?: string; accountId?: string }[] = [];
   for (const account of snapshot.accounts) {
     const domain = account.domain?.trim().toLowerCase().replace(/^www\./, "");
-    if (domain && domains.has(domain)) accountIds.add(account.id);
+    if (domain && domains.has(domain)) {
+      accountIds.add(account.id);
+      viaDomain = true;
+    }
   }
   for (const contact of snapshot.contacts) {
     const email = contact.email?.trim().toLowerCase();
     const at = email ? email.indexOf("@") : -1;
     if (email && at > 0 && domains.has(email.slice(at + 1)) && contact.accountId) {
       accountIds.add(contact.accountId);
+      viaEmail = true;
+      matchedContacts.push({ id: contact.id, ...(contact.email ? { email: contact.email } : {}), accountId: contact.accountId });
     }
   }
+  const resolvedVia = viaDomain && viaEmail ? "both" : viaDomain ? "account_domain" : "contact_email";
+  const via = { resolvedVia, ...(matchedContacts.length ? { matchedContacts } : {}) } as const;
   if (accountIds.size === 0) {
     return {
       dealId: null,
@@ -432,8 +451,9 @@ export function suggestCallDeal(
       dealName: top.name,
       accountId: top.accountId,
       accountName: account?.name,
+      ...via,
       confidence: "high",
-      reason: `"${top.name}" is the only open deal on matched account "${account?.name ?? top.accountId}".`,
+      reason: `"${top.name}" is the only open deal on matched account "${account?.name ?? top.accountId}" (via ${resolvedVia}).`,
     };
   }
   return {
@@ -441,8 +461,9 @@ export function suggestCallDeal(
     dealName: top.name,
     accountId: top.accountId,
     accountName: account?.name,
+    ...via,
     confidence: "low",
-    reason: `${openDeals.length} open deals on matched account(s); "${top.name}" has the most recent activity. Confirm before writing.`,
+    reason: `${openDeals.length} open deals on matched account(s); "${top.name}" has the most recent activity (matched via ${resolvedVia}). Confirm before writing.`,
   };
 }
 

package/src/cli.ts

@@ -125,6 +125,11 @@ import {
   remaining,
   type AcquireRemaining,
 } from "./acquireMeter.ts";
+import {
+  scaffoldWorkspace,
+  type InitProvider,
+  type InitSource,
+} from "./init.ts";
 import {
   crmContactKeys,
   fetchExploriumProspects,
@@ -246,6 +251,10 @@ Usage:
   the process list and shell history. Pipe them on stdin or enter them at the
   interactive prompt:
     echo "$HUBSPOT_TOKEN" | fullstackgtm login hubspot
+  fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
+                                               cold start: scaffold icp.json + enrich.config.json + a
+                                               PLAYBOOK wired for this workspace (the CLI ships primitives,
+                                               your agent is the orchestrator — see docs/recipes.md)
   fullstackgtm snapshot [source options] [--since <iso>] [--out <path> | --archive <dir>]
   fullstackgtm audit [source options] [audit options] [--save]
   fullstackgtm report [source options] [audit options] [report options]
@@ -466,6 +475,17 @@ type HelpEntry = {
 };
 
 const HELP: Record<string, HelpEntry> = {
+  // Get started
+  init: {
+    summary: "scaffold a workspace (icp.json + enrich.config.json + PLAYBOOK)",
+    phase: "Setup",
+    synopsis: [
+      "fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]",
+    ],
+    detail:
+      "Cold start: writes a starter ICP, an acquire-ready enrich.config.json (with a visible assign seam so leads are never ownerless), and a PLAYBOOK wired with the cold-start + outbound-loop recipes for this workspace. Pure file-writer — no network, keeps existing files unless --force. The CLI ships governed primitives; your coding agent is the orchestrator (see docs/recipes.md).",
+    seeAlso: ["icp", "enrich", "signals"],
+  },
   // Setup & health
   login: {
     summary: "connect a provider or LLM key (secrets via stdin/env, never argv)",
@@ -726,12 +746,13 @@ const HELP: Record<string, HelpEntry> = {
 
 // Verbs that print their own richer multi-subcommand help; runCli routes their
 // `--help` to themselves, so commandHelp() only renders these via `help <verb>`.
-const BESPOKE_HELP = ["call", "market", "enrich", "bulk-update", "schedule", "signals", "icp", "draft"];
+const BESPOKE_HELP = ["init", "call", "market", "enrich", "bulk-update", "schedule", "signals", "icp", "draft"];
 
 // Lifecycle-grouped front door. One line per verb, organized by the
 // Prevent→Detect→Remediate→Verify loop so a new user sees ~6 jobs, not 22 verbs.
 function shortUsage() {
   const groups: Array<[string, string[]]> = [
+    ["Get started", ["init"]],
     ["Setup & health", ["login", "logout", "doctor", "profiles", "health"]],
     ["Detect — read-only", ["audit", "report", "snapshot", "diff", "rules"]],
     ["Prevent — gate writes", ["resolve"]],
@@ -2659,7 +2680,8 @@ NEVER emits a patch plan; --save persists only the local signal ledger (used by
       throw new Error(`signals outcome: --result must be one of ${valid.join(", ")}.`);
     }
     const touchId = option(rest, "--touch") ?? undefined;
-    const outcome = makeOutcome({ accountDomain: accountArg, touchId, result: result as SignalOutcomeResult });
+    const contactId = option(rest, "--contact") ?? undefined;
+    const outcome = makeOutcome({ accountDomain: accountArg, touchId, contactId, result: result as SignalOutcomeResult });
     await createFileSignalStore().appendOutcome(outcome);
     console.error(
       `Recorded outcome "${outcome.result}" for ${outcome.accountDomain} (${outcome.id}). ` +
@@ -2840,6 +2862,63 @@ LLM key it emits a clearly-labeled stub rather than fake authored copy.`);
   }
 }
 
+/**
+ * `init` — scaffold a GTM workspace from cold scratch: a starter icp.json, an
+ * enrich.config.json (acquire preset + a visible assign seam), and a PLAYBOOK
+ * wired with the chosen source/provider that points at the recipes. Pure
+ * file-writer: no network, never overwrites without --force.
+ */
+function initCommand(args: string[]) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`Usage:
+  fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
+
+Scaffolds a workspace so the first acquire/signals/judge/draft commands work:
+  icp.json            starter ICP (edit, or rebuild with \`icp interview\`)
+  enrich.config.json  acquire preset for --source + a placeholder assign policy
+  PLAYBOOK.md         the cold-start + outbound-loop recipes wired for this workspace
+
+The CLI ships governed primitives; your coding agent is the orchestrator. See
+docs/recipes.md for the full play set. Existing files are kept unless --force.`);
+    return;
+  }
+  const source = (option(args, "--source") ?? "pipe0") as InitSource;
+  if (!["pipe0", "explorium", "linkedin"].includes(source)) {
+    throw new Error(`init: --source must be pipe0|explorium|linkedin (got "${source}")`);
+  }
+  const provider = (option(args, "--provider") ?? "hubspot") as InitProvider;
+  if (!["hubspot", "salesforce"].includes(provider)) {
+    throw new Error(`init: --provider must be hubspot|salesforce (got "${provider}")`);
+  }
+  const outDir = resolve(process.cwd(), option(args, "--out") ?? ".");
+  const force = args.includes("--force");
+  const current = activeProfile();
+  const profile = current === DEFAULT_PROFILE ? undefined : current;
+
+  const files = scaffoldWorkspace({ source, provider, profile });
+  const wrote: string[] = [];
+  const kept: string[] = [];
+  for (const file of files) {
+    const path = resolve(outDir, file.path);
+    if (existsSync(path) && !force) {
+      kept.push(file.path);
+      continue;
+    }
+    writeFileSync(path, file.content);
+    wrote.push(file.path);
+  }
+
+  console.log(
+    `Scaffolded workspace (${provider}, discovery via ${source}${profile ? `, profile ${profile}` : ""}).`,
+  );
+  if (wrote.length) console.log(`  wrote: ${wrote.join(", ")}`);
+  if (kept.length) console.log(`  kept (use --force to overwrite): ${kept.join(", ")}`);
+  console.log(
+    "\nNext: edit icp.json + set acquire.assign.ownerId in enrich.config.json, then follow PLAYBOOK.md\n" +
+      "(full recipe set: docs/recipes.md).",
+  );
+}
+
 /**
  * `icp` — develop and inspect the Ideal Customer Profile that targets acquire.
  * The CLI can't run AskUserQuestion itself; `icp interview` emits the question
@@ -2929,12 +3008,20 @@ ops. Develop one by interview, then \`enrich acquire\` picks up ./icp.json.
     const unjudged = signalRun.signals.filter((s) => !s.judgedBy);
     if (unjudged.length === 0) throw new Error(`Signal run "${signalRun.runLabel}" has no unjudged signals.`);
 
-    // 2) Optional inputs: ICP (may be undefined), snapshot (only --with-history),
-    //    outcomes + config from the signal store / DEFAULT_SIGNALS_CONFIG.
+    // 2) Optional inputs: ICP (may be undefined), snapshot, outcomes + config.
+    //    The snapshot is loaded whenever a source is given (--provider/--input/
+    //    --demo/--sample) — it resolves each decision's CRM target (accountId +
+    //    best contact) so `draft` can write against a real record. --with-history
+    //    additionally enables the memory + fit scoring inputs.
     const icp = loadIcp(rest);
     const config: SignalsConfig = DEFAULT_SIGNALS_CONFIG;
     const outcomes = await signalStore.listOutcomes();
-    const snapshot = withHistory ? await readSnapshot(rest) : undefined;
+    const hasSnapshotSource =
+      Boolean(option(rest, "--provider")) ||
+      Boolean(option(rest, "--input")) ||
+      rest.includes("--demo") ||
+      rest.includes("--sample");
+    const snapshot = withHistory || hasSnapshotSource ? await readSnapshot(rest) : undefined;
 
     // 3) Resolve the LLM seam ONLY if a key already exists (deterministic baseline
     //    otherwise — never PROMPT here; judge must run key-free).
@@ -5206,6 +5293,10 @@ export async function runCli(argv: string[]) {
     await enrichCommand(args);
     return;
   }
+  if (command === "init") {
+    initCommand(args);
+    return;
+  }
   if (command === "icp") {
     await icpCommand(args);
     return;

package/src/connector.ts

@@ -2,6 +2,7 @@ import { dedupeKey } from "./dedupe.ts";
 import { requiresHumanInput } from "./rules.ts";
 import type {
   CanonicalGtmSnapshot,
+  CreateRecordPayload,
   GtmConnector,
   PatchOperation,
   PatchOperationResult,
@@ -283,7 +284,43 @@ export async function applyPatchPlan(
     }
   }
 
+  // Bulk fast-path: route independent, approved create_record CONTACT ops
+  // through the connector's batch API (batched resolve-first read + batched
+  // writes) instead of one round-trip per record. Only ops that are safe to
+  // batch are eligible — every other op (grouped, needs an override, carries a
+  // company association, conflicted, or any non-create op) stays on the serial
+  // path below, so the safety contract is unchanged. Results are merged in by
+  // id; the serial loop short-circuits anything already resolved here.
+  const batched = new Map<string, PatchOperationResult>();
+  if (connector.applyCreateContactsBatch && !guardFailure) {
+    const eligible = plan.operations.filter(
+      (operation) =>
+        approved.has(operation.id) &&
+        operation.operation === "create_record" &&
+        operation.objectType === "contact" &&
+        options.valueOverrides?.[operation.id] === undefined &&
+        !requiresHumanInput(operation.afterValue) &&
+        !operation.groupId &&
+        !(operation.afterValue as CreateRecordPayload | undefined)?.associateCompanyName &&
+        !conflicts.has(operation.id) &&
+        !irreversibleStale.has(operation.id) &&
+        !(staleByFilter && staleByFilter.has(operation.objectId)),
+    );
+    // Only worth the batch machinery for more than a couple of creates.
+    if (eligible.length > 2) {
+      const batchResults = await connector.applyCreateContactsBatch(eligible);
+      for (const result of batchResults) batched.set(result.operationId, result);
+    }
+  }
+
   for (const operation of plan.operations) {
+    const batchedResult = batched.get(operation.id);
+    if (batchedResult) {
+      results.push(batchedResult);
+      attempted += 1;
+      if (batchedResult.status === "applied") applied += 1;
+      continue;
+    }
     if (!approved.has(operation.id)) {
       results.push({
         operationId: operation.id,

package/src/connectors/hubspot.ts

@@ -506,18 +506,34 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     };
   }
 
-  /** Exact-name company lookup for resolve-first creates. Returns matching ids (max 3 fetched). */
-  async function searchCompaniesByName(name: string): Promise<string[]> {
+  /** Exact-value company lookup (by `name` or `domain`) for resolve-first creates. */
+  async function searchCompaniesBy(property: string, value: string): Promise<string[]> {
     const data = await request(`/crm/v3/objects/companies/search`, {
       method: "POST",
       body: JSON.stringify({
-        filterGroups: [{ filters: [{ propertyName: "name", operator: "EQ", value: name }] }],
-        properties: ["name"],
+        filterGroups: [{ filters: [{ propertyName: property, operator: "EQ", value }] }],
+        properties: [property],
         limit: 3,
       }),
     });
     return ((data?.results ?? []) as Array<{ id: string }>).map((row) => String(row.id));
   }
+  const searchCompaniesByName = (name: string) => searchCompaniesBy("name", name);
+
+  /** Stamp `domain` on a company only when it has none (fill-blank, never clobber). */
+  async function fillCompanyDomainIfEmpty(companyId: string, domain: string): Promise<void> {
+    try {
+      const data = await request(`/crm/v3/objects/companies/${encodeURIComponent(companyId)}?properties=domain`);
+      const current = data?.properties?.domain;
+      if (typeof current === "string" && current.trim()) return; // already has one — leave it
+      await request(`/crm/v3/objects/companies/${encodeURIComponent(companyId)}`, {
+        method: "PATCH",
+        body: JSON.stringify({ properties: { domain } }),
+      });
+    } catch {
+      // Best-effort: a failed domain fill must not sink the contact create.
+    }
+  }
 
   /** Exact-value contact lookup (by any searchable property) for resolve-first creates. */
   async function searchContactsBy(property: string, value: string): Promise<string[]> {
@@ -533,36 +549,51 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   }
 
   /**
-   * Resolve a company by exact name, creating it on a confirmed miss. Returns
-   * the company id, or null on ambiguity (≥2 existing) so the caller skips the
-   * association rather than guessing. Same-run safe via createdCompaniesByName.
+   * Resolve a company to a real account record, creating it on a confirmed miss.
+   * Matches by DOMAIN first (the accurate key) and falls back to exact name;
+   * creates with the domain stamped, and fills the domain on a name-matched
+   * account that lacks one — so the account is signal-watchable. Returns null on
+   * ambiguity (≥2 matches) so the caller skips the association rather than
+   * guessing. Same-run safe via createdCompaniesByName.
    */
-  async function resolveOrCreateCompanyByName(name: string, opId: string): Promise<string | null> {
-    const nameKey = name.toLowerCase();
-    const already = createdCompaniesByName.get(nameKey);
+  async function resolveOrCreateCompany(name: string, domain: string | undefined, opId: string): Promise<string | null> {
+    const cacheKey = domain ? `d:${domain.toLowerCase()}` : `n:${name.toLowerCase()}`;
+    const already = createdCompaniesByName.get(cacheKey);
     if (already) return already;
-    const matches = await searchCompaniesByName(name);
-    if (matches.length > 1) return null;
-    if (matches.length === 1) {
-      createdCompaniesByName.set(nameKey, matches[0]);
-      return matches[0];
+
+    // 1. Domain-first match (accurate; an account matched here already has it).
+    if (domain) {
+      const byDomain = await searchCompaniesBy("domain", domain);
+      if (byDomain.length > 1) return null;
+      if (byDomain.length === 1) {
+        createdCompaniesByName.set(cacheKey, byDomain[0]);
+        return byDomain[0];
+      }
+    }
+    // 2. Exact-name match; stamp the domain if the account has none.
+    const byName = await searchCompaniesByName(name);
+    if (byName.length > 1) return null;
+    if (byName.length === 1) {
+      if (domain) await fillCompanyDomainIfEmpty(byName[0], domain);
+      createdCompaniesByName.set(cacheKey, byName[0]);
+      return byName[0];
     }
+    // 3. Create with name + domain (provenance is best-effort).
+    const props: Record<string, string> = { name, ...(domain ? { domain } : {}) };
     let created;
     try {
       created = await request(`/crm/v3/objects/companies`, {
         method: "POST",
-        body: JSON.stringify({
-          properties: { name, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` },
-        }),
+        body: JSON.stringify({ properties: { ...props, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` } }),
       });
     } catch {
       created = await request(`/crm/v3/objects/companies`, {
         method: "POST",
-        body: JSON.stringify({ properties: { name } }),
+        body: JSON.stringify({ properties: props }),
       });
     }
     const id = String(created.id);
-    createdCompaniesByName.set(nameKey, id);
+    createdCompaniesByName.set(cacheKey, id);
     return id;
   }
 
@@ -588,7 +619,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     }
 
     if (operation.objectType === "account") {
-      const id = await resolveOrCreateCompanyByName(matchValue, operation.id);
+      const id = await resolveOrCreateCompany(matchValue, stringOrUndefined(payload.properties?.domain), operation.id);
       if (id === null) {
         return { operationId: operation.id, status: "skipped", detail: `create_record: ambiguous — multiple companies named "${matchValue}". Not creating.` };
       }
@@ -637,13 +668,14 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     let companyNote = "";
     if (payload.associateCompanyName) {
       try {
-        const companyId = await resolveOrCreateCompanyByName(payload.associateCompanyName, operation.id);
+        const companyId = await resolveOrCreateCompany(payload.associateCompanyName, payload.associateCompanyDomain, operation.id);
         if (companyId) {
           await request(
             `/crm/v4/objects/contacts/${encodeURIComponent(contactId)}/associations/default/companies/${encodeURIComponent(companyId)}`,
             { method: "PUT" },
           );
-          companyNote = ` Linked to company "${payload.associateCompanyName}" (${companyId}).`;
+          const domainNote = payload.associateCompanyDomain ? ` (${payload.associateCompanyDomain})` : "";
+          companyNote = ` Linked to company "${payload.associateCompanyName}"${domainNote} (${companyId}).`;
         } else {
           companyNote = ` Company "${payload.associateCompanyName}" was ambiguous; left unlinked.`;
         }
@@ -660,6 +692,130 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     };
   }
 
+  /** Bulk resolve-first lookup: which match values already exist (value→id). */
+  async function searchContactsByValues(property: string, values: string[]): Promise<Map<string, string>> {
+    const found = new Map<string, string>();
+    for (let i = 0; i < values.length; i += 100) {
+      const chunk = values.slice(i, i + 100);
+      const data = await request(`/crm/v3/objects/contacts/search`, {
+        method: "POST",
+        body: JSON.stringify({
+          filterGroups: [{ filters: [{ propertyName: property, operator: "IN", values: chunk }] }],
+          properties: [property],
+          limit: 100,
+        }),
+      });
+      for (const rec of (data?.results ?? []) as Array<{ id?: string; properties?: Record<string, string> }>) {
+        const v = rec?.properties?.[property];
+        if (typeof v === "string" && rec.id) found.set(v.toLowerCase(), String(rec.id));
+      }
+    }
+    return found;
+  }
+
+  /**
+   * Batch create_record for contacts: bulk resolve-first (search IN), then
+   * bulk-create the genuine misses (batch/create, 100/call) — two API calls per
+   * ~100 leads instead of two per lead. On a batch-create rejection (e.g. an
+   * email collision HubSpot 409s the whole batch over), it falls back to
+   * per-record createRecord for that chunk, so one bad row never sinks the rest
+   * and resolve-first is preserved. Returns one result per input op.
+   */
+  async function applyCreateContactsBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    const byId = new Map<string, PatchOperationResult>();
+    // Group by the HubSpot search property (matchKey is usually uniform across a
+    // plan, but a mixed plan stays correct this way).
+    const groups = new Map<string, PatchOperation[]>();
+    for (const op of operations) {
+      const matchKey = (op.afterValue as CreateRecordPayload | undefined)?.matchKey || "email";
+      const searchProperty = HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts[matchKey] ?? matchKey;
+      let arr = groups.get(searchProperty);
+      if (!arr) groups.set(searchProperty, (arr = []));
+      arr.push(op);
+    }
+
+    for (const [searchProperty, ops] of groups) {
+      const wanted = ops
+        .map((op) => String((op.afterValue as CreateRecordPayload).matchValue ?? "").trim())
+        .filter(Boolean);
+      const existing = await searchContactsByValues(searchProperty, [...new Set(wanted.map((v) => v.toLowerCase()))]);
+
+      const toCreate: PatchOperation[] = [];
+      const seenInBatch = new Set<string>();
+      for (const op of ops) {
+        const payload = op.afterValue as CreateRecordPayload;
+        const matchKey = payload.matchKey || "email";
+        const matchValue = String(payload.matchValue ?? "").trim();
+        if (!matchValue) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." });
+          continue;
+        }
+        const lower = matchValue.toLowerCase();
+        const dedupeKey = `${matchKey}:${lower}`;
+        const already = createdContactsByMatch.get(dedupeKey);
+        if (already) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: already, existing: true } });
+          continue;
+        }
+        const existingId = existing.get(lower);
+        if (existingId) {
+          createdContactsByMatch.set(dedupeKey, existingId);
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existingId}); resolve-first declined to create.`, providerData: { id: existingId, existing: true } });
+          continue;
+        }
+        if (seenInBatch.has(lower)) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} duplicated within this batch; not duplicating.` });
+          continue;
+        }
+        seenInBatch.add(lower);
+        toCreate.push(op);
+      }
+
+      for (let i = 0; i < toCreate.length; i += 100) {
+        const chunk = toCreate.slice(i, i + 100);
+        const inputs = chunk.map((op) => {
+          const payload = op.afterValue as CreateRecordPayload;
+          const properties: Record<string, string> = { ...payload.properties };
+          if (payload.ownerId && !properties.hubspot_owner_id) properties.hubspot_owner_id = String(payload.ownerId);
+          properties.hs_object_source_detail_2 = `fullstackgtm acquire (${op.id})`;
+          return { properties };
+        });
+        try {
+          const data = await request(`/crm/v3/objects/contacts/batch/create`, {
+            method: "POST",
+            body: JSON.stringify({ inputs }),
+          });
+          const created = (data?.results ?? []) as Array<{ id?: string; properties?: Record<string, string> }>;
+          const idByValue = new Map<string, string>();
+          for (const rec of created) {
+            const v = rec?.properties?.[searchProperty];
+            if (typeof v === "string" && rec.id) idByValue.set(v.toLowerCase(), String(rec.id));
+          }
+          for (const op of chunk) {
+            const payload = op.afterValue as CreateRecordPayload;
+            const matchKey = payload.matchKey || "email";
+            const matchValue = String(payload.matchValue).trim();
+            const id = idByValue.get(matchValue.toLowerCase());
+            if (id) {
+              createdContactsByMatch.set(`${matchKey}:${matchValue.toLowerCase()}`, id);
+              byId.set(op.id, { operationId: op.id, status: "applied", detail: `Created contact ${matchKey}=${matchValue} (${id}).`, providerData: { id, created: true } });
+            } else {
+              // Result didn't echo this value — resolve it per-record to be safe.
+              byId.set(op.id, await createRecord(op));
+            }
+          }
+        } catch {
+          // Whole-chunk rejection (e.g. a collision). Isolate per record.
+          for (const op of chunk) byId.set(op.id, await createRecord(op));
+        }
+      }
+    }
+
+    return operations.map(
+      (op) => byId.get(op.id) ?? { operationId: op.id, status: "skipped", detail: "create_record was not processed." },
+    );
+  }
+
   async function createTask(operation: PatchOperation): Promise<PatchOperationResult> {
     const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
     if (associationTypeId === undefined) {
@@ -926,6 +1082,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     fetchSnapshot,
     fetchChanges,
     applyOperation,
+    applyCreateContactsBatch,
     readField,
   };
 }