@koda-sl/baker-cli 0.464.0 → 0.466.0

package/dist/map-4OMNZZCB.js

@@ -0,0 +1,403 @@
+import {
+  MappingError,
+  buildFieldMapping,
+  describeSlots,
+  namesComeFromAccount,
+  otherSlots,
+  shapeFor
+} from "./chunk-ADUQKLUO.js";
+import {
+  collectConfigStatus,
+  collectSideEffects,
+  flowDataPath,
+  readFlowTree,
+  requestFlowInputCall,
+  sideEffectNeedsInput,
+  writeFlowTree
+} from "./chunk-CT4JJID6.js";
+import {
+  repeatedFlagValues
+} from "./chunk-ERSX3MKH.js";
+import "./chunk-ZJVHZHYP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-ML7DLFFY.js";
+import {
+  apiPost
+} from "./chunk-P5NYZ236.js";
+import "./chunk-7JB56IVP.js";
+import "./chunk-XMS5K54U.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-MEBOQXW3.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/flows/map.ts
+import { readFileSync } from "fs";
+import { defineCommand } from "citty";
+registerSchema({
+  command: "flows.map",
+  description: "Map form fields onto any named value a side effect sends: a CRM fieldMapping, a sheet columnMapping, a webhook payloadKeys, a pixel eventParams, or a platform matching block. Emits the mapping and splices it in with --write. Configure the destination through request_flow_input FIRST \u2014 the destination-side names come from the connected account, not from you.",
+  args: {
+    slug: { type: "positional", description: "Form slug (folder under flows/)", required: true },
+    map: {
+      type: "string",
+      description: "<destField>[:<fieldType>]=<value>, repeatable. Omit both this and --from to be told what the side effect accepts instead. Sheet: A=name. HubSpot with --hubspot-form: firstname=nombre (the type is read off the form). Where a destination cannot be read, state the type on the LEFT \u2014 c0ffee:varchar=email \u2014 because `:` on the right belongs to the value grammar.",
+      required: false
+    },
+    from: {
+      type: "string",
+      description: 'The whole mapping as a JSON file, or `-` for stdin: { "sideEffect": "\u2026", "map": { "<destField>": "<value>", \u2026 } }. Past ~3 fields prefer this over repeated --map.',
+      required: false
+    },
+    "side-effect": { type: "string", description: "Side-effect id, when the form has more than one", required: false },
+    "hubspot-form": {
+      type: "string",
+      description: "HubSpot formGuid of the configured destination. Fills every mapping's fieldType and objectTypeId from the form itself, so you write no types at all. The guid is the `formGuid` in the `destination` request_flow_input returned.",
+      required: false
+    },
+    into: {
+      type: "string",
+      description: "Slot to map into when the type has more than one: meta/tiktok/pinterest take eventParams (default) or their matching record; googleAds takes enhancedConversions or value/currency/transactionId.",
+      required: false
+    },
+    entity: {
+      type: "string",
+      description: "Destination object (pipedrive: person|organization|lead, \u2026)",
+      required: false
+    },
+    custom: { type: "boolean", description: "The destination fields are custom fields", required: false },
+    standard: { type: "boolean", description: "The destination fields are standard fields", required: false },
+    "object-type": { type: "string", description: "HubSpot objectTypeId (default 0-1, contact)", required: false },
+    "prune-missing": {
+      type: "boolean",
+      description: "Drop the mappings whose destination field no longer exists on the account, and nothing else. The repair for a deleted HubSpot property: HubSpot refuses the WHOLE submission when it names a field it does not have, so one dead mapping loses every lead. Needs --hubspot-form so the live field list can be read. Runs on its own \u2014 no --map required. Prefer this to --replace, which drops everything this call does not name.",
+      required: false
+    },
+    replace: {
+      type: "boolean",
+      description: "Make the slot exactly what this call passes, dropping every mapping already in it. Without it, mappings MERGE by destination name \u2014 re-mapping a name overwrites it, a new name is appended, and the rest are left alone. To REMOVE a dead mapping, reach for --prune-missing instead: this one also deletes every mapping you did not re-state.",
+      required: false
+    },
+    write: {
+      type: "boolean",
+      description: "Splice the mapping into the form. Without it, prints and changes nothing",
+      required: false
+    }
+  }
+});
+function mapSpecsFrom(rawArgs) {
+  return repeatedFlagValues(rawArgs, "map");
+}
+function specsFromFile(parsed) {
+  return Object.entries(parsed.map ?? {}).map(([destField, entry]) => {
+    if (typeof entry === "string") return `${destField}=${entry}`;
+    const type = entry?.type ? `:${entry.type}` : "";
+    return `${destField}${type}=${entry?.value ?? ""}`;
+  });
+}
+function readSpecFile(path) {
+  let raw;
+  try {
+    raw = path === "-" ? readFileSync(0, "utf-8") : readFileSync(path, "utf-8");
+  } catch (error) {
+    refuse(
+      `Could not read ${path === "-" ? "the mapping from stdin" : `"${path}"`}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    refuse(
+      `${path === "-" ? "stdin" : `"${path}"`} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      'Expected { "map": { "<destField>": "<value>", \u2026 } }'
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    refuse("A mapping file must be a JSON object.", 'Expected { "map": { "<destField>": "<value>", \u2026 } }');
+  }
+  const spec = parsed;
+  if (!spec.map || typeof spec.map !== "object" || Object.keys(spec.map).length === 0) {
+    refuse("A mapping file needs a non-empty `map` object.", 'Expected { "map": { "firstname": "nombre", \u2026 } }');
+  }
+  return spec;
+}
+function refuse(message, fix) {
+  writeJson({ ok: false, error: { code: "VALIDATION_ERROR", message, ...fix ? { fix } : {} } });
+  process.exit(1);
+}
+async function hubspotFieldCatalog(formId) {
+  let response;
+  try {
+    response = await apiPost("/api/hubspot/forms/view", { formId });
+  } catch (error) {
+    refuse(
+      `Could not read HubSpot form "${formId}": ${error instanceof Error ? error.message : String(error)}`,
+      "Check the guid against the `destination` request_flow_input returned, or `baker hubspot forms list`. Drop --hubspot-form and write `<field>:<fieldType>=<value>` per mapping only if HubSpot is unreachable."
+    );
+  }
+  const fields = response.data.form?.fields ?? [];
+  if (fields.length === 0) {
+    refuse(
+      `HubSpot form "${formId}" reports no fields, so nothing can be mapped against it.`,
+      "Confirm the guid names the form this side effect submits to: baker hubspot forms list"
+    );
+  }
+  return {
+    fields: new Map(
+      fields.map((field) => [
+        field.name,
+        { fieldType: field.fieldType, ...field.objectTypeId ? { objectTypeId: field.objectTypeId } : {} }
+      ])
+    ),
+    // Read while the form is already open, because this is the moment a
+    // delivery is being wired: HubSpot refuses every submission sent to a form
+    // with spam prevention on, so a mapping written against one is correct and
+    // will still never arrive. Reported, not refused — the mapping is not the
+    // mistake, and the client can switch it off without the work being redone.
+    captchaEnabled: response.data.form?.captchaEnabled === true
+  };
+}
+function describeDestination(chosen) {
+  const type = String(chosen.sideEffect.type ?? "");
+  const slots = describeSlots(type);
+  if (slots.length === 0) {
+    refuse(
+      `A ${type} side effect has no mappable field.`,
+      `Nothing on it addresses named values. \`baker flows schema side-effect ${type}\` shows what it does take.`
+    );
+  }
+  writeJson({
+    ok: true,
+    data: { sideEffectId: chosen.sideEffect.id, type, mappable: slots },
+    hints: [
+      `Nothing mapped \u2014 this is what a ${type} side effect accepts. Add --map <key>=<value> to build one.`,
+      ...slots.map(
+        (slot) => slot.keys ? `${slot.slot}: ${slot.keys.join(", ")}` : `${slot.slot}: ${slot.keysFrom === "account" ? "keys come from the connected account (request_flow_input returns them)" : "keys are yours to choose \u2014 whatever the receiving system expects"}`
+      ),
+      // Named separately from the key hint above: the key and its field type are
+      // two different questions with two different answers, and the type is the
+      // one an agent does not know it is being asked until a mapping is refused.
+      ...slots.flatMap((slot) => slot.fieldTypes ? [`${slot.slot} field types \u2014 ${slot.fieldTypes}`] : []),
+      'Values (right of the `=`) are the same for every slot: a form field, tracking:<var>, global:<name>, code:<name>, a "literal", or those joined with +. A field may also be written as the file stores it, {{<stepId>.customForm.<field>}}. A value cannot run code (no .split(), .slice(), [0]).'
+    ]
+  });
+}
+function shapeOrRefuse(type, into) {
+  try {
+    return shapeFor(type, into);
+  } catch (error) {
+    if (error instanceof MappingError) refuse(error.message, error.fix);
+    throw error;
+  }
+}
+function assertDestinationReady(slug, tree, chosen, into) {
+  if (!sideEffectNeedsInput(chosen.sideEffect)) return;
+  const type = String(chosen.sideEffect.type ?? "");
+  const status = collectConfigStatusFor(tree, slug, String(chosen.sideEffect.id ?? ""));
+  const call = status ? requestFlowInputCall(slug, status) : `request_flow_input for the ${type} side effect`;
+  if (!namesComeFromAccount(shapeOrRefuse(type, into))) return;
+  refuse(
+    `The ${type} destination is not configured yet, so its field names cannot be anything but a guess.`,
+    `Configure it first, then map against the names that call returns: ${call}`
+  );
+}
+function collectConfigStatusFor(tree, _slug, sideEffectId) {
+  const rows = [];
+  collectConfigStatus(tree, rows);
+  return rows.find((row) => row.sideEffectId === sideEffectId);
+}
+function slotHintFor(type, into) {
+  const others = otherSlots(type, shapeFor(type, into));
+  if (others.length === 0) return [];
+  return [`This side effect also takes ${others.join(" and ")} \u2014 pass --into <slot> to map into one of those instead.`];
+}
+function survivorHint(built, replacing) {
+  if (built.kept > 0) {
+    return [`${built.kept} mapping${built.kept === 1 ? "" : "s"} already in ${built.key} kept \u2014 this merged by name.`];
+  }
+  if (!replacing) return [];
+  return [`--replace: ${built.key} is now exactly these ${built.count}; anything else it held is gone.`];
+}
+function droppedHint(built) {
+  if (built.dropped.length === 0) return [];
+  return [
+    `--prune-missing dropped ${built.dropped.length} mapping${built.dropped.length === 1 ? "" : "s"} the destination no longer has: ${built.dropped.join(", ")}. Every other mapping in ${built.key} was left alone.`
+  ];
+}
+function pendingEndpointHint(slug, tree, chosen) {
+  if (!sideEffectNeedsInput(chosen.sideEffect)) return [];
+  const status = collectConfigStatusFor(tree, slug, String(chosen.sideEffect.id ?? ""));
+  if (!status) return [];
+  return [`The mapping is written, but this destination still needs the user: ${requestFlowInputCall(slug, status)}`];
+}
+function pickSideEffect(slug, found, named) {
+  if (found.length === 0) {
+    refuse(
+      `"${slug}" has no side effects \u2014 author the side effect first, then map into it.`,
+      `baker flows add-side-effect ${slug} --node <nodeId> --type <type>`
+    );
+  }
+  const chosen = named ? found.find((entry) => entry.sideEffect.id === named) : found.length === 1 ? found[0] : void 0;
+  if (chosen) return chosen;
+  const inventory = found.map((entry) => `${entry.sideEffect.id} (${entry.sideEffect.type})`).join(", ");
+  refuse(
+    named ? `No side effect with id "${named}" in "${slug}".` : `"${slug}" has ${found.length} side effects \u2014 name one with --side-effect <id>.`,
+    `Side effects in this form: ${inventory}`
+  );
+}
+function customFlag(custom, standard) {
+  if (custom === true && standard === true) {
+    refuse("--custom and --standard contradict each other. Pass one.");
+  }
+  if (custom === true) return true;
+  if (standard === true) return false;
+  return void 0;
+}
+async function mapOptions(args, fromFile, into) {
+  const hubspotForm = args["hubspot-form"] ? String(args["hubspot-form"]) : fromFile?.hubspotForm;
+  const catalog = hubspotForm ? await hubspotFieldCatalog(hubspotForm) : void 0;
+  return {
+    options: {
+      into,
+      entity: args.entity ? String(args.entity) : fromFile?.entity,
+      isCustomField: customFlag(args.custom, args.standard) ?? fromFile?.custom,
+      objectType: args["object-type"] ? String(args["object-type"]) : fromFile?.objectType,
+      replace: args.replace === true || fromFile?.replace === true,
+      pruneMissing: args["prune-missing"] === true || fromFile?.pruneMissing === true,
+      destinationFields: catalog?.fields
+    },
+    hints: catalog?.captchaEnabled ? [
+      "WARNING: this HubSpot form has spam prevention (captcha) on. HubSpot refuses every submission sent to a form with it on, so nothing mapped here will arrive \u2014 the mapping is fine, the destination is not. Only the user can switch it off, on the form in HubSpot. Tell them that, and do not swap the destination yourself."
+    ] : []
+  };
+}
+var mapCommand = defineCommand({
+  meta: {
+    name: "map",
+    description: "Map form fields onto any value a side effect sends \u2014 never hand-write a mapping. Start here: baker flows map contact --from map.json --write"
+  },
+  args: {
+    slug: { type: "positional", description: "Form slug", required: true },
+    map: { type: "string", description: "<destField>[:<fieldType>]=<value> (repeatable)" },
+    from: { type: "string", description: "Read the whole mapping from a JSON file, or `-` for stdin" },
+    "side-effect": { type: "string", description: "Side-effect id, when the form has more than one" },
+    "hubspot-form": {
+      type: "string",
+      description: "HubSpot formGuid \u2014 reads every field's type off the form so you write none"
+    },
+    into: {
+      type: "string",
+      description: "Which slot to map into, for a type with more than one (e.g. meta: eventParams | advancedMatching)"
+    },
+    entity: { type: "string", description: "Destination object (person, contact, lead, \u2026)" },
+    custom: { type: "boolean", description: "Destination fields are custom fields" },
+    standard: { type: "boolean", description: "Destination fields are standard fields" },
+    "object-type": { type: "string", description: "HubSpot objectTypeId (default 0-1)" },
+    "prune-missing": {
+      type: "boolean",
+      description: "Drop only the mappings the destination no longer has \u2014 the repair for a deleted HubSpot field"
+    },
+    replace: {
+      type: "boolean",
+      description: "Drop every mapping already in the slot. Default merges by destination name"
+    },
+    write: { type: "boolean", description: "Splice the mapping into the form" }
+  },
+  run: async ({ args, rawArgs }) => {
+    const slug = String(args.slug);
+    const fromFile = args.from ? readSpecFile(String(args.from)) : void 0;
+    const specs = fromFile ? specsFromFile(fromFile) : mapSpecsFrom(rawArgs);
+    const into = args.into ? String(args.into) : fromFile?.into;
+    const replacing = args.replace === true || fromFile?.replace === true;
+    const pruning = args["prune-missing"] === true || fromFile?.pruneMissing === true;
+    const tree = readFlowTree(slug);
+    const chosen = pickSideEffect(
+      slug,
+      collectSideEffects(tree),
+      args["side-effect"] ? String(args["side-effect"]) : fromFile?.sideEffect
+    );
+    if (specs.length === 0 && !pruning) {
+      describeDestination(chosen);
+      return;
+    }
+    assertDestinationReady(slug, tree, chosen, into);
+    const { options, hints: destinationHints } = await mapOptions(args, fromFile, into);
+    let built;
+    try {
+      built = buildFieldMapping(tree, chosen.sideEffect, specs, options);
+    } catch (error) {
+      if (error instanceof MappingError) {
+        refuse(error.message, error.fix);
+      }
+      throw error;
+    }
+    const slotHint = [
+      ...destinationHints,
+      ...droppedHint(built),
+      ...survivorHint(built, replacing),
+      ...slotHintFor(String(chosen.sideEffect.type ?? ""), into),
+      ...pendingEndpointHint(slug, tree, chosen)
+    ];
+    if (args.write !== true) {
+      emitDryRun(slug, chosen, built, slotHint);
+      return;
+    }
+    Object.assign(chosen.sideEffect, built.patch);
+    writeFlowTree(slug, tree);
+    emitWritten(slug, chosen, built, slotHint);
+  }
+});
+function mapHeadline(built, phase, slug = "") {
+  const wrote = `${built.count} ${built.key} mapping${built.count === 1 ? "" : "s"}`;
+  const drops = `${built.dropped.length} dead mapping${built.dropped.length === 1 ? "" : "s"}`;
+  if (phase === "dry-run") {
+    if (built.count === 0 && built.dropped.length > 0) {
+      return `Nothing written. Re-run with --write to drop ${drops} from ${slug}.`;
+    }
+    return `Nothing written. Re-run with --write to splice ${wrote} into ${slug}.`;
+  }
+  if (built.dropped.length === 0) return `Wrote ${wrote}.`;
+  if (built.count === 0) return `Dropped ${drops} from ${built.key}; nothing else changed.`;
+  return `Wrote ${wrote} and dropped ${drops}.`;
+}
+function emitDryRun(slug, chosen, built, slotHint) {
+  writeJson({
+    ok: true,
+    data: {
+      sideEffectId: chosen.sideEffect.id,
+      type: chosen.sideEffect.type,
+      key: built.key,
+      patch: built.patch
+    },
+    hints: [mapHeadline(built, "dry-run", slug), ...slotHint]
+  });
+}
+function emitWritten(slug, chosen, built, slotHint) {
+  writeJson({
+    ok: true,
+    data: {
+      sideEffectId: chosen.sideEffect.id,
+      type: chosen.sideEffect.type,
+      key: built.key,
+      written: built.count,
+      kept: built.kept,
+      dropped: built.dropped,
+      path: flowDataPath(slug)
+    },
+    hints: [
+      mapHeadline(built, "written"),
+      `A mapping is only real once the destination is set \u2014 check with: baker flows show ${slug}`,
+      ...slotHint
+    ]
+  });
+}
+export {
+  mapCommand,
+  mapHeadline,
+  mapSpecsFrom,
+  specsFromFile
+};
+//# sourceMappingURL=map-4OMNZZCB.js.map