strapi-plugin-hubspot 0.4.2 → 0.6.0

package/dist/server/index.mjs

@@ -1,5 +1,5 @@
 import { errors } from "@strapi/utils";
-const HS_BASE$1 = "https://api.hubapi.com";
+const HS_BASE$2 = "https://api.hubapi.com";
 const TTL_MS = 10 * 60 * 1e3;
 const STANDARD_OBJECTS = [
   { name: "contact", path: "contacts" },
@@ -13,7 +13,7 @@ const STANDARD_OBJECTS = [
 let cache = null;
 let inFlight = null;
 async function hsGet(apiKey, path) {
-  const res = await fetch(`${HS_BASE$1}${path}`, {
+  const res = await fetch(`${HS_BASE$2}${path}`, {
     headers: { Authorization: `Bearer ${apiKey}` }
   });
   if (!res.ok) {
@@ -352,7 +352,92 @@ async function runAudit(strapi, targets, schema) {
   }
   return reports;
 }
+const localizedString = (type = "string") => ({
+  type,
+  pluginOptions: { i18n: { localized: true } }
+});
 const contentTypes = {
+  /**
+   * A form built in the plugin's builder page. The flat, queryable identity
+   * lives as attributes; the structure (steps → fields → conditions) lives in
+   * `definition`, a versioned JSON document — plugins cannot ship components,
+   * and the builder is a better editor for it than the Content Manager, which
+   * is why the type is hidden there.
+   */
+  form: {
+    schema: {
+      kind: "collectionType",
+      collectionName: "hubspot_forms",
+      info: {
+        singularName: "form",
+        pluralName: "forms",
+        displayName: "HubSpot forms",
+        description: "Forms built in the HubSpot form builder"
+      },
+      options: { draftAndPublish: true },
+      pluginOptions: {
+        "content-manager": { visible: false },
+        "content-type-builder": { visible: false },
+        i18n: { localized: true }
+      },
+      attributes: {
+        name: {
+          type: "string",
+          required: true,
+          pluginOptions: { i18n: { localized: false } }
+        },
+        slug: {
+          type: "uid",
+          targetField: "name",
+          required: true
+        },
+        title: localizedString(),
+        subtitle: localizedString("text"),
+        nextLabel: localizedString(),
+        submitLabel: localizedString(),
+        successMessage: localizedString("text"),
+        definition: {
+          type: "json",
+          required: true,
+          pluginOptions: { i18n: { localized: true } }
+        }
+      }
+    }
+  },
+  /**
+   * One visitor submission of a built form — the source of truth for the
+   * lead, stored whatever the CRM's mood. Visible in the Content Manager so
+   * the team can browse and export; hidden from the Content-Type Builder.
+   */
+  submission: {
+    schema: {
+      kind: "collectionType",
+      collectionName: "hubspot_submissions",
+      info: {
+        singularName: "submission",
+        pluralName: "submissions",
+        displayName: "HubSpot form submissions",
+        description: "Visitor submissions of the forms built with the plugin"
+      },
+      options: { draftAndPublish: false },
+      pluginOptions: {
+        "content-manager": { visible: true },
+        "content-type-builder": { visible: false }
+      },
+      attributes: {
+        form: { type: "string", required: true },
+        formTitle: { type: "string" },
+        email: { type: "email" },
+        values: { type: "json", required: true },
+        meta: { type: "json" },
+        locale: { type: "string" },
+        hubspotSynced: { type: "boolean", default: false },
+        contactId: { type: "string" },
+        companyId: { type: "string" },
+        rejected: { type: "json" }
+      }
+    }
+  },
   failure: {
     schema: {
       kind: "collectionType",
@@ -378,6 +463,728 @@ const contentTypes = {
     }
   }
 };
+const NEEDS_VALUE = /* @__PURE__ */ new Set(["eq", "neq", "contains", "gt", "lt"]);
+function validateDefinition(definition) {
+  const errors2 = [];
+  const allIds = /* @__PURE__ */ new Set();
+  for (const step of definition.steps ?? []) {
+    for (const fld of step.fields ?? []) allIds.add(fld.id);
+  }
+  const checkCondition = (condition, seen2, owner) => {
+    for (const rule of condition?.rules ?? []) {
+      if (!allIds.has(rule.field)) {
+        errors2.push({ code: "unknown-field", ...owner, target: rule.field });
+      } else if (!seen2.has(rule.field)) {
+        errors2.push({ code: "forward-reference", ...owner, target: rule.field });
+      }
+      if (NEEDS_VALUE.has(rule.operator) && (rule.value === void 0 || rule.value === "")) {
+        errors2.push({ code: "missing-value", ...owner, target: rule.field });
+      }
+    }
+  };
+  const seen = /* @__PURE__ */ new Set();
+  const seenNames = /* @__PURE__ */ new Set();
+  for (const step of definition.steps ?? []) {
+    checkCondition(step.visibleIf, seen, { stepId: step.id });
+    for (const fld of step.fields ?? []) {
+      if (!fld.name?.trim()) {
+        errors2.push({ code: "missing-name", fieldId: fld.id, name: fld.name ?? "" });
+      } else if (seenNames.has(fld.name)) {
+        errors2.push({ code: "duplicate-name", fieldId: fld.id, name: fld.name });
+      } else {
+        seenNames.add(fld.name);
+      }
+      checkCondition(fld.visibleIf, seen, { fieldId: fld.id });
+      seen.add(fld.id);
+    }
+  }
+  return errors2;
+}
+const isPrimitive = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+const isEmpty = (v) => v === void 0 || v === null || v === false || typeof v === "string" && v.trim() === "";
+const asString = (v) => typeof v === "string" ? v.trim() : v === void 0 || v === null ? "" : String(v);
+const asNumber = (v) => typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+function evaluateRule(rule, get) {
+  const value = get(rule.field);
+  switch (rule.operator) {
+    case "eq":
+      return asString(value) === asString(rule.value);
+    case "neq":
+      return asString(value) !== asString(rule.value);
+    case "contains":
+      return asString(value).toLowerCase().includes(asString(rule.value).toLowerCase());
+    case "empty":
+      return isEmpty(value);
+    case "notEmpty":
+      return !isEmpty(value);
+    case "gt": {
+      const [a, b] = [asNumber(value), asNumber(rule.value)];
+      return Number.isFinite(a) && Number.isFinite(b) && a > b;
+    }
+    case "lt": {
+      const [a, b] = [asNumber(value), asNumber(rule.value)];
+      return Number.isFinite(a) && Number.isFinite(b) && a < b;
+    }
+    default:
+      return false;
+  }
+}
+function evaluateCondition(condition, get) {
+  if (!condition || !condition.rules?.length) return true;
+  const results = condition.rules.map((rule) => evaluateRule(rule, get));
+  return condition.logic === "or" ? results.some(Boolean) : results.every(Boolean);
+}
+function resolveSubmission(definition, rawValues) {
+  const visibleById = /* @__PURE__ */ new Map();
+  const get = (fieldId) => visibleById.get(fieldId);
+  const values = {};
+  const hidden = [];
+  const missingRequired = [];
+  const declared = /* @__PURE__ */ new Set();
+  for (const step of definition.steps ?? []) {
+    const stepVisible = evaluateCondition(step.visibleIf, get);
+    for (const fld of step.fields ?? []) {
+      declared.add(fld.name);
+      const visible = stepVisible && evaluateCondition(fld.visibleIf, get);
+      if (!visible) {
+        hidden.push(fld.name);
+        continue;
+      }
+      const raw = rawValues[fld.name];
+      const value = typeof raw === "string" ? raw.trim() : raw;
+      const submitted = isPrimitive(value) && !isEmpty(value) ? value : void 0;
+      visibleById.set(fld.id, submitted);
+      if (submitted !== void 0) {
+        values[fld.name] = submitted;
+      } else if (fld.required) {
+        missingRequired.push({ id: fld.id, name: fld.name, label: fld.label ?? fld.name });
+      }
+    }
+  }
+  const unknown = Object.keys(rawValues).filter((key) => !declared.has(key));
+  return { values, hidden, missingRequired, unknown };
+}
+function publicForm(entry) {
+  return {
+    slug: entry.slug,
+    title: entry.title ?? null,
+    subtitle: entry.subtitle ?? null,
+    nextLabel: entry.nextLabel ?? null,
+    submitLabel: entry.submitLabel ?? null,
+    successMessage: entry.successMessage ?? null,
+    locale: entry.locale ?? null,
+    steps: (entry.definition?.steps ?? []).map((step) => ({
+      ...step,
+      fields: (step.fields ?? []).map(({ hubspot: _hubspot, ...fld }) => fld)
+    }))
+  };
+}
+function groupByObject(definition, values) {
+  const groups = {};
+  for (const step of definition.steps ?? []) {
+    for (const fld of step.fields ?? []) {
+      const value = values[fld.name];
+      if (value === void 0) continue;
+      const mapping = fld.hubspot ?? {};
+      const object = mapping.object?.trim() || "contact";
+      const property = mapping.property?.trim() || fld.name;
+      (groups[object] ??= {})[property] = value;
+    }
+  }
+  return groups;
+}
+function mappingProblems(definition, portalProperties) {
+  const problems = [];
+  for (const step of definition.steps ?? []) {
+    for (const fld of step.fields ?? []) {
+      const mapping = fld.hubspot ?? {};
+      if (!mapping.property) continue;
+      const options = fld.options;
+      const problem = checkMapping(portalProperties, {
+        object: mapping.object?.trim() || "contact",
+        property: mapping.property,
+        values: options?.map((o) => o.value ?? "").filter(Boolean)
+      });
+      if (problem) problems.push({ ...problem, fieldId: fld.id });
+    }
+  }
+  return problems;
+}
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+function findEmail(values) {
+  const candidates = [values.email, ...Object.values(values)];
+  for (const v of candidates) {
+    if (typeof v === "string" && EMAIL_RE.test(v.trim())) return v.trim().toLowerCase();
+  }
+  return void 0;
+}
+const FREEMAIL = /* @__PURE__ */ new Set([
+  "gmail.com",
+  "googlemail.com",
+  "yahoo.com",
+  "yahoo.fr",
+  "hotmail.com",
+  "hotmail.fr",
+  "outlook.com",
+  "outlook.fr",
+  "live.com",
+  "live.fr",
+  "msn.com",
+  "icloud.com",
+  "me.com",
+  "aol.com",
+  "free.fr",
+  "orange.fr",
+  "wanadoo.fr",
+  "sfr.fr",
+  "laposte.net",
+  "gmx.com",
+  "proton.me",
+  "protonmail.com",
+  "yopmail.com"
+]);
+function corporateDomain(email) {
+  const domain = email?.split("@")[1]?.toLowerCase();
+  return domain && !FREEMAIL.has(domain) ? domain : void 0;
+}
+const SUBMISSION_UID = "plugin::hubspot.submission";
+const MAX_FIELDS = 40;
+const MAX_VALUE_LEN = 5e3;
+function sanitizeRawValues(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const entries = Object.entries(raw);
+  if (entries.length > MAX_FIELDS) return null;
+  const values = {};
+  for (const [key, value] of entries) {
+    if (typeof value === "string") values[key] = value.slice(0, MAX_VALUE_LEN);
+    else if (typeof value === "boolean" || typeof value === "number") values[key] = value;
+  }
+  return values;
+}
+const HS_BASE$1 = "https://api.hubapi.com";
+const HS_COMPANIES = `${HS_BASE$1}/crm/v3/objects/companies`;
+const HS_NOTES = `${HS_BASE$1}/crm/v3/objects/notes`;
+const ASSOC_NOTE_TO_CONTACT = 202;
+const ASSOC_NOTE_TO_COMPANY = 190;
+const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+async function hsJson(apiKey, url, init) {
+  const res = await fetch(url, {
+    method: init.method,
+    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+    body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(body.message || `HubSpot ${res.status}`);
+  return body;
+}
+function summaryLines(definition, values) {
+  const lines = [];
+  for (const step of definition.steps ?? []) {
+    for (const fld of step.fields ?? []) {
+      const value = values[fld.name];
+      if (value === void 0) continue;
+      const options = fld.options;
+      const label = options?.find((o) => o.value === String(value))?.label;
+      lines.push(
+        `<strong>${escapeHtml(fld.label ?? fld.name)}</strong> : ${escapeHtml(String(label ?? value))}`
+      );
+    }
+  }
+  return lines;
+}
+function createFormsService(strapi, _opts = {}) {
+  const formsConfig = () => ({
+    companyFromDomain: true,
+    timelineNote: true,
+    ...strapi.plugin("hubspot").config("forms", {})
+  });
+  async function partitionBySchema(apiKey, groups) {
+    let schema;
+    try {
+      schema = await loadSchema(
+        strapi,
+        apiKey,
+        resolveObjects(strapi.plugin("hubspot").config("objects", []))
+      );
+    } catch {
+      return { accepted: groups, rejected: [] };
+    }
+    const accepted = {};
+    const rejected = [];
+    for (const [object, props] of Object.entries(groups)) {
+      for (const [property, value] of Object.entries(props)) {
+        const problem = checkMapping(schema.properties, {
+          object,
+          property,
+          values: String(value).split(";").map((v) => v.trim()).filter(Boolean)
+        });
+        if (problem) rejected.push(problem);
+        else (accepted[object] ??= {})[property] = value;
+      }
+    }
+    return { accepted, rejected };
+  }
+  async function resolveCompanyByDomain(apiKey, domain, props) {
+    const found = await hsJson(apiKey, `${HS_COMPANIES}/search`, {
+      method: "POST",
+      body: {
+        filterGroups: [{ filters: [{ propertyName: "domain", operator: "EQ", value: domain }] }],
+        properties: ["domain"],
+        limit: 1
+      }
+    });
+    const stringProps = { domain };
+    for (const [key, value] of Object.entries(props)) stringProps[key] = String(value);
+    const existingId = found.results?.[0]?.id;
+    if (existingId) {
+      await hsJson(apiKey, `${HS_COMPANIES}/${existingId}`, {
+        method: "PATCH",
+        body: { properties: stringProps }
+      });
+      return existingId;
+    }
+    const created = await hsJson(apiKey, HS_COMPANIES, {
+      method: "POST",
+      body: { properties: stringProps }
+    });
+    return created.id;
+  }
+  async function createLeadNote(apiKey, opts) {
+    const lines = [];
+    const title = opts.form.title || opts.form.name;
+    lines.push(`<strong>Nouveau lead${title ? ` — ${escapeHtml(String(title))}` : ""}</strong>`);
+    if (opts.meta.pageUrl) lines.push(`Page : ${escapeHtml(String(opts.meta.pageUrl))}`);
+    if (opts.meta.originLabel) {
+      const path = opts.meta.originPath ? ` (${escapeHtml(String(opts.meta.originPath))})` : "";
+      lines.push(`<strong>Sujet</strong> : ${escapeHtml(String(opts.meta.originLabel))}${path}`);
+    }
+    lines.push("", ...summaryLines(opts.form.definition, opts.values));
+    if (opts.rejected.length) {
+      lines.push("", "<strong>⚠ Champs non enregistrés (mapping à corriger)</strong>");
+      for (const r of opts.rejected) {
+        lines.push(`${escapeHtml(r.object)}.${escapeHtml(r.property)} — ${escapeHtml(r.code)}`);
+      }
+    }
+    const associations = [
+      {
+        to: { id: opts.contactId },
+        types: [
+          { associationCategory: "HUBSPOT_DEFINED", associationTypeId: ASSOC_NOTE_TO_CONTACT }
+        ]
+      }
+    ];
+    if (opts.companyId) {
+      associations.push({
+        to: { id: opts.companyId },
+        types: [
+          { associationCategory: "HUBSPOT_DEFINED", associationTypeId: ASSOC_NOTE_TO_COMPANY }
+        ]
+      });
+    }
+    await hsJson(apiKey, HS_NOTES, {
+      method: "POST",
+      body: {
+        properties: { hs_timestamp: (/* @__PURE__ */ new Date()).toISOString(), hs_note_body: lines.join("<br>") },
+        associations
+      }
+    });
+  }
+  async function submit(form, rawValues, meta = {}) {
+    const resolution = resolveSubmission(form.definition, rawValues);
+    if (resolution.missingRequired.length) {
+      return { ok: false, missingRequired: resolution.missingRequired };
+    }
+    const email = findEmail(resolution.values);
+    const { apiKey } = await resolveApiKey(strapi);
+    const config2 = formsConfig();
+    let hubspotSynced = false;
+    let contactId;
+    let companyId;
+    let rejected = [];
+    if (email && apiKey) {
+      const groups = groupByObject(form.definition, resolution.values);
+      const partition = await partitionBySchema(apiKey, groups);
+      rejected = partition.rejected;
+      const result = await strapi.plugin("hubspot").service("submit").upsert({
+        object: "contact",
+        idProperty: "email",
+        properties: { ...partition.accepted.contact ?? {}, email }
+      });
+      if (result.ok) {
+        hubspotSynced = true;
+        contactId = result.id;
+      }
+      const domain = corporateDomain(email);
+      if (contactId && domain && config2.companyFromDomain) {
+        try {
+          companyId = await resolveCompanyByDomain(
+            apiKey,
+            domain,
+            partition.accepted.company ?? {}
+          );
+          if (companyId) {
+            await hsJson(
+              apiKey,
+              `${HS_BASE$1}/crm/v4/objects/contacts/${contactId}/associations/default/companies/${companyId}`,
+              { method: "PUT" }
+            );
+          }
+        } catch (err) {
+          strapi.log.warn(`[hubspot] company sync failed (contact OK) — ${err.message}`);
+        }
+      }
+      if (contactId && config2.timelineNote) {
+        try {
+          await createLeadNote(apiKey, {
+            contactId,
+            companyId,
+            form,
+            meta,
+            values: resolution.values,
+            rejected
+          });
+        } catch (err) {
+          strapi.log.warn(`[hubspot] lead note failed (contact OK) — ${err.message}`);
+        }
+      }
+    }
+    await strapi.documents(SUBMISSION_UID).create({
+      data: {
+        form: form.slug,
+        formTitle: form.title || form.name,
+        email,
+        values: resolution.values,
+        meta,
+        locale: form.locale ?? null,
+        hubspotSynced,
+        contactId,
+        companyId,
+        rejected
+      }
+    });
+    return { ok: true, hubspotSynced };
+  }
+  return { submit };
+}
+let counter = 0;
+const makeId = (prefix) => `${prefix}_${Date.now().toString(36)}${(counter += 1).toString(36)}`;
+const slugifyName = (label) => label.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+const FIELD_DEFAULTS = {
+  label: "label",
+  name: "name",
+  object: "hsObject",
+  property: "hsProperty",
+  type: "type",
+  placeholder: "placeholder",
+  required: "required",
+  icon: "icon",
+  options: "options",
+  width: "width",
+  helpText: "helpText",
+  class: "class",
+  persist: "persist"
+};
+const STEP_DEFAULTS = {
+  title: "title",
+  description: "description",
+  class: "class"
+};
+function convertLegacyForm(entry, map = {}) {
+  const stepMap = { ...STEP_DEFAULTS, ...map.step };
+  const fieldMap = { ...FIELD_DEFAULTS, ...map.field };
+  const rawSteps = entry[map.steps ?? "steps"] ?? [];
+  const steps = rawSteps.map((rawStep) => {
+    const rawFields = rawStep[map.fields ?? "fields"] ?? [];
+    return {
+      id: makeId("stp"),
+      title: rawStep[stepMap.title] ?? void 0,
+      description: rawStep[stepMap.description] ?? void 0,
+      class: rawStep[stepMap.class] ?? void 0,
+      fields: rawFields.map((raw) => {
+        const label = raw[fieldMap.label] ?? "";
+        const object = raw[fieldMap.object] ?? void 0;
+        const property = raw[fieldMap.property] ?? void 0;
+        const options = raw[fieldMap.options] ?? [];
+        return {
+          id: makeId("fld"),
+          label,
+          name: (raw[fieldMap.name] || slugifyName(label)) ?? "",
+          type: raw[fieldMap.type] ?? "text",
+          placeholder: raw[fieldMap.placeholder] ?? void 0,
+          required: Boolean(raw[fieldMap.required]),
+          icon: raw[fieldMap.icon] ?? void 0,
+          width: raw[fieldMap.width] ?? void 0,
+          helpText: raw[fieldMap.helpText] ?? void 0,
+          class: raw[fieldMap.class] ?? void 0,
+          persist: raw[fieldMap.persist] ?? void 0,
+          ...options.length ? { options: options.map((o) => ({ value: o.value ?? "", label: o.label ?? void 0 })) } : {},
+          ...object || property ? { hubspot: { object, property } } : {}
+        };
+      })
+    };
+  });
+  return {
+    name: entry.name ?? "",
+    slug: entry.slug ?? "",
+    title: entry.title ?? null,
+    subtitle: entry.subtitle ?? null,
+    nextLabel: entry.nextLabel ?? null,
+    submitLabel: entry.submitLabel ?? null,
+    successMessage: entry.successMessage ?? null,
+    definition: { version: 1, steps }
+  };
+}
+const FORM_UID = "plugin::hubspot.form";
+const EMPTY_DEFINITION = { version: 1, steps: [] };
+const WRITABLE = [
+  "name",
+  "title",
+  "subtitle",
+  "nextLabel",
+  "submitLabel",
+  "successMessage"
+];
+const slugify = (value) => value.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "form";
+function createFormsAdminController(strapi) {
+  const documents = () => strapi.documents(FORM_UID);
+  async function checkMappings(definition) {
+    const { apiKey } = await resolveApiKey(strapi);
+    if (!apiKey) return null;
+    try {
+      const schema = await loadSchema(
+        strapi,
+        apiKey,
+        resolveObjects(strapi.plugin("hubspot").config("objects", []))
+      );
+      return mappingProblems(definition, schema.properties);
+    } catch {
+      return null;
+    }
+  }
+  function pickWritable(body) {
+    const data = {};
+    for (const key of WRITABLE) {
+      if (key in body) data[key] = body[key];
+    }
+    return data;
+  }
+  function requireValidDefinition(ctx, definition) {
+    const def = definition ?? EMPTY_DEFINITION;
+    const errors2 = validateDefinition(def);
+    if (errors2.length) {
+      ctx.status = 400;
+      ctx.body = { errors: errors2 };
+      throw Object.assign(new Error("invalid definition"), { handled: true });
+    }
+    return def;
+  }
+  const handled = (err) => err?.handled === true;
+  return {
+    async list(ctx) {
+      const locale = ctx.query.locale;
+      const drafts = await documents().findMany({
+        locale,
+        status: "draft",
+        sort: "updatedAt:desc"
+      });
+      const published = await documents().findMany({
+        locale,
+        status: "published",
+        fields: ["slug"]
+      });
+      const publishedIds = new Set(published.map((e) => e.documentId));
+      ctx.body = {
+        forms: drafts.map((entry) => ({
+          documentId: entry.documentId,
+          name: entry.name,
+          slug: entry.slug,
+          updatedAt: entry.updatedAt,
+          published: publishedIds.has(entry.documentId),
+          steps: (entry.definition?.steps ?? []).length,
+          fields: (entry.definition?.steps ?? []).reduce(
+            (n, step) => n + (step.fields?.length ?? 0),
+            0
+          )
+        }))
+      };
+    },
+    async findOne(ctx) {
+      const entry = await documents().findOne({
+        documentId: ctx.params.documentId,
+        locale: ctx.query.locale,
+        status: "draft"
+      });
+      if (!entry) ctx.throw(404, "Form not found");
+      const published = await documents().findOne({
+        documentId: ctx.params.documentId,
+        locale: ctx.query.locale,
+        status: "published"
+      });
+      ctx.body = { form: entry, published: Boolean(published) };
+    },
+    async create(ctx) {
+      const body = ctx.request.body ?? {};
+      const name = typeof body.name === "string" ? body.name.trim() : "";
+      if (!name) ctx.throw(400, "A form needs a name");
+      const base = slugify(name);
+      let slug = base;
+      for (let i = 2; ; i += 1) {
+        const clash = await documents().findFirst({ filters: { slug } });
+        if (!clash) break;
+        slug = `${base}-${i}`;
+      }
+      let definition;
+      try {
+        definition = requireValidDefinition(ctx, body.definition);
+      } catch (err) {
+        if (handled(err)) return;
+        throw err;
+      }
+      const entry = await documents().create({
+        locale: ctx.query.locale,
+        data: { ...pickWritable(body), name, slug, definition }
+      });
+      ctx.body = { form: entry };
+    },
+    async update(ctx) {
+      const body = ctx.request.body ?? {};
+      let definition;
+      if ("definition" in body) {
+        try {
+          definition = requireValidDefinition(ctx, body.definition);
+        } catch (err) {
+          if (handled(err)) return;
+          throw err;
+        }
+      }
+      const entry = await documents().update({
+        documentId: ctx.params.documentId,
+        locale: ctx.query.locale,
+        data: { ...pickWritable(body), ...definition ? { definition } : {} }
+      });
+      if (!entry) ctx.throw(404, "Form not found");
+      const problems = definition ? await checkMappings(definition) : null;
+      ctx.body = { form: entry, problems: problems ?? [] };
+    },
+    async publish(ctx) {
+      const entry = await documents().findOne({
+        documentId: ctx.params.documentId,
+        locale: ctx.query.locale,
+        status: "draft"
+      });
+      if (!entry) ctx.throw(404, "Form not found");
+      const structural = validateDefinition(entry.definition ?? EMPTY_DEFINITION);
+      const mappings = await checkMappings(entry.definition ?? EMPTY_DEFINITION) ?? [];
+      if (structural.length || mappings.length) {
+        ctx.status = 400;
+        ctx.body = { errors: structural, problems: mappings };
+        return;
+      }
+      await documents().publish({
+        documentId: ctx.params.documentId,
+        locale: ctx.query.locale
+      });
+      ctx.body = { ok: true };
+    },
+    async unpublish(ctx) {
+      await documents().unpublish({
+        documentId: ctx.params.documentId,
+        locale: ctx.query.locale
+      });
+      ctx.body = { ok: true };
+    },
+    /** Entries of the configured legacy content type, offered for import. */
+    async listSources(ctx) {
+      const config2 = strapi.plugin("hubspot").config("forms", {}).import;
+      if (!config2?.uid) {
+        ctx.body = { configured: false, sources: [] };
+        return;
+      }
+      try {
+        const entries = await strapi.documents(config2.uid).findMany({
+          fields: ["name", "slug"],
+          sort: "name:asc"
+        });
+        ctx.body = {
+          configured: true,
+          sources: entries.map((e) => ({
+            documentId: e.documentId,
+            name: e.name ?? e.slug ?? e.documentId,
+            slug: e.slug ?? ""
+          }))
+        };
+      } catch (err) {
+        strapi.log.warn(`[hubspot] import sources unavailable — ${err.message}`);
+        ctx.body = { configured: true, sources: [] };
+      }
+    },
+    /**
+     * Converts one legacy entry (every locale of it) into a plugin form
+     * draft. Same slug: re-importing overwrites the draft, never touches the
+     * published version, and never modifies the source.
+     */
+    async runImport(ctx) {
+      const config2 = strapi.plugin("hubspot").config("forms", {}).import;
+      if (!config2?.uid) ctx.throw(400, "No import source configured (forms.import.uid)");
+      const sourceId = ctx.request.body?.documentId;
+      if (typeof sourceId !== "string" || !sourceId) ctx.throw(400, "documentId is required");
+      const { uid, ...map } = config2;
+      const populate = {
+        [map.steps ?? "steps"]: {
+          populate: {
+            [map.fields ?? "fields"]: { populate: [map.field?.options ?? "options"] }
+          }
+        }
+      };
+      let locales = [void 0];
+      try {
+        const found = await strapi.plugin("i18n").service("locales").find();
+        if (Array.isArray(found) && found.length) {
+          locales = [...found].sort((a, b) => Number(b.isDefault ?? false) - Number(a.isDefault ?? false)).map((l) => l.code);
+        }
+      } catch {
+      }
+      let targetId = null;
+      let imported = 0;
+      for (const locale of locales) {
+        const source = await strapi.documents(uid).findOne({
+          documentId: sourceId,
+          locale,
+          populate
+        });
+        if (!source) continue;
+        const converted = convertLegacyForm(source, map);
+        if (!targetId) {
+          const existing = await documents().findFirst({
+            filters: { slug: converted.slug }
+          });
+          targetId = existing?.documentId ?? null;
+        }
+        const data = { ...converted };
+        if (targetId) {
+          delete data.slug;
+          await documents().update({ documentId: targetId, locale, data });
+        } else {
+          const created = await documents().create({
+            locale,
+            data
+          });
+          targetId = created.documentId;
+        }
+        imported += 1;
+      }
+      if (!targetId) ctx.throw(404, "Source entry not found");
+      ctx.body = { documentId: targetId, locales: imported };
+    },
+    async remove(ctx) {
+      await documents().delete({
+        documentId: ctx.params.documentId
+        // No locale: deleting a form deletes all its locales.
+      });
+      ctx.body = { ok: true };
+    }
+  };
+}
 const HS_BASE = "https://api.hubapi.com";
 const FAILURE_UID = "plugin::hubspot.failure";
 const RETRY_DELAYS_MS = [500, 2e3];
@@ -514,13 +1321,19 @@ function createSubmitService(strapi, { sleep = sleepFor } = {}) {
   return { upsert, retryFailures };
 }
 const SETTINGS_ACTION = "plugin::hubspot.settings";
+const FORMS_ACTION = "plugin::hubspot.forms";
 const config = {
   default: {
     apiKey: "",
     // Objects whose properties are offered. Names from the standard set, or
     // `{ name, path }` for a custom object type.
     objects: ["contact", "company"],
-    validate: []
+    validate: [],
+    // Submission pipeline of the built forms. Both default to true:
+    //  - companyFromDomain: a corporate email upserts the Company (deduped by
+    //    domain) and associates it to the contact;
+    //  - timelineNote: a note recaps the submission on the contact's timeline.
+    forms: { companyFromDomain: true, timelineNote: true }
   },
   validator(cfg) {
     if (cfg.validate && !Array.isArray(cfg.validate)) {
@@ -581,6 +1394,42 @@ const controllers = {
       ctx.body = await strapi.plugin("hubspot").service("submit").retryFailures();
     }
   }),
+  formsAdmin: ({ strapi }) => createFormsAdminController(strapi),
+  forms: ({ strapi }) => ({
+    /** Published form for the host frontend — CRM mapping stripped. */
+    async findOne(ctx) {
+      const entry = await strapi.documents(FORM_UID).findFirst({
+        filters: { slug: ctx.params.slug },
+        status: "published",
+        locale: ctx.query.locale
+      });
+      if (!entry?.definition) ctx.throw(404, "Form not found");
+      ctx.body = publicForm(entry);
+    },
+    async submit(ctx) {
+      const entry = await strapi.documents(FORM_UID).findFirst({
+        filters: { slug: ctx.params.slug },
+        status: "published",
+        locale: ctx.query.locale
+      });
+      if (!entry?.definition) ctx.throw(404, "Form not found");
+      const values = sanitizeRawValues(ctx.request.body?.values);
+      if (!values || !Object.keys(values).length) ctx.throw(422, "Invalid submission");
+      const rawMeta = ctx.request.body?.meta ?? {};
+      const meta = {};
+      for (const key of ["pagePath", "pageUrl", "originPath", "originLabel", "source"]) {
+        const v = rawMeta[key];
+        if (typeof v === "string" && v) meta[key] = v.slice(0, 500);
+      }
+      const outcome = await strapi.plugin("hubspot").service("forms").submit(entry, values, meta);
+      if (!outcome.ok) {
+        ctx.status = 422;
+        ctx.body = { ok: false, missingRequired: outcome.missingRequired ?? [] };
+        return;
+      }
+      ctx.body = { ok: true, hubspotSynced: outcome.hubspotSynced };
+    }
+  }),
   settings: ({ strapi }) => ({
     async get(ctx) {
       ctx.body = await publicSettings(strapi);
@@ -619,7 +1468,26 @@ const routes = {
       adminRoute("POST", "/failures/retry", "failures.retry", [SETTINGS_ACTION]),
       adminRoute("GET", "/settings", "settings.get", [SETTINGS_ACTION]),
       adminRoute("PUT", "/settings", "settings.update", [SETTINGS_ACTION]),
-      adminRoute("DELETE", "/settings", "settings.reset", [SETTINGS_ACTION])
+      adminRoute("DELETE", "/settings", "settings.reset", [SETTINGS_ACTION]),
+      adminRoute("GET", "/builder/forms", "formsAdmin.list", [FORMS_ACTION]),
+      adminRoute("POST", "/builder/forms", "formsAdmin.create", [FORMS_ACTION]),
+      adminRoute("GET", "/builder/forms/:documentId", "formsAdmin.findOne", [FORMS_ACTION]),
+      adminRoute("PUT", "/builder/forms/:documentId", "formsAdmin.update", [FORMS_ACTION]),
+      adminRoute("POST", "/builder/forms/:documentId/publish", "formsAdmin.publish", [FORMS_ACTION]),
+      adminRoute("POST", "/builder/forms/:documentId/unpublish", "formsAdmin.unpublish", [FORMS_ACTION]),
+      adminRoute("DELETE", "/builder/forms/:documentId", "formsAdmin.remove", [FORMS_ACTION]),
+      adminRoute("GET", "/builder/import/sources", "formsAdmin.listSources", [FORMS_ACTION]),
+      adminRoute("POST", "/builder/import", "formsAdmin.runImport", [FORMS_ACTION])
+    ]
+  },
+  // Public form delivery + submission, under /api/hubspot/…. Like any
+  // content-api route, they must be granted to the Public role in
+  // Settings → Users & Permissions before the frontend can call them.
+  "content-api": {
+    type: "content-api",
+    routes: [
+      { method: "GET", path: "/forms/:slug", handler: "forms.findOne", config: { policies: [] } },
+      { method: "POST", path: "/forms/:slug/submit", handler: "forms.submit", config: { policies: [] } }
     ]
   }
 };
@@ -629,7 +1497,8 @@ const index = {
   controllers,
   routes,
   services: {
-    submit: ({ strapi }) => createSubmitService(strapi)
+    submit: ({ strapi }) => createSubmitService(strapi),
+    forms: ({ strapi }) => createFormsService(strapi)
   },
   register({ strapi }) {
     strapi.customFields.register({
@@ -650,6 +1519,12 @@ const index = {
         displayName: "Access the HubSpot settings",
         uid: "settings",
         pluginName: "hubspot"
+      },
+      {
+        section: "plugins",
+        displayName: "Use the HubSpot form builder",
+        uid: "forms",
+        pluginName: "hubspot"
       }
     ]);
     const targets = strapi.plugin("hubspot").config("validate", []);