strapi-plugin-hubspot 0.15.0 → 0.16.0

package/dist/server/index.mjs

@@ -176,6 +176,26 @@ const first = (values, fallback = "") => {
   }
   return { value: fallback, source: null };
 };
+const MODES = /* @__PURE__ */ new Set(["auto", "crm", "forms"]);
+function asSubmissionMode(value) {
+  return typeof value === "string" && MODES.has(value) ? value : void 0;
+}
+function asBool(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function formsCfg(strapi) {
+  return strapi.plugin("hubspot").config("forms", {}) ?? {};
+}
+function policyFrom(stored, forms) {
+  return {
+    submissionMode: asSubmissionMode(stored.submissionMode) ?? asSubmissionMode(forms.submissionMode) ?? "auto",
+    writeExtraProperties: asBool(stored.writeExtraProperties) ?? asBool(forms.writeExtraProperties) ?? true,
+    syncFieldsOnPublish: asBool(stored.syncFieldsOnPublish) ?? asBool(forms.syncFieldsOnPublish) ?? false
+  };
+}
+async function resolvePolicy(strapi) {
+  return policyFrom(await getStoredSettings(strapi), formsCfg(strapi));
+}
 async function resolveApiKey(strapi) {
   const stored = await getStoredSettings(strapi);
   if (stored.apiKey) return { apiKey: stored.apiKey, source: "settings" };
@@ -195,7 +215,7 @@ async function resolveAccount(strapi) {
 }
 async function resolveAccountSources(strapi) {
   const stored = await getStoredSettings(strapi);
-  const formsCfg = strapi.plugin("hubspot").config("forms", {}) ?? {};
+  const forms = formsCfg(strapi);
   const portal = first([
     { value: stored.portalId, source: "settings" },
     { value: strapi.plugin("hubspot").config("portalId", ""), source: "config" },
@@ -211,10 +231,11 @@ async function resolveAccountSources(strapi) {
   );
   const form = first([
     { value: stored.defaultFormId, source: "settings" },
-    { value: formsCfg.defaultFormId, source: "config" },
+    { value: forms.defaultFormId, source: "config" },
     { value: process.env[ENV_DEFAULT_FORM], source: "env" }
   ]);
   const { apiKey, source: keySource } = await resolveApiKey(strapi);
+  const policy = policyFrom(stored, forms);
   return {
     configured: Boolean(apiKey),
     keySource,
@@ -224,7 +245,8 @@ async function resolveAccountSources(strapi) {
     defaultFormId: form.value,
     portalSource: portal.source,
     regionSource: region.source,
-    formSource: form.source
+    formSource: form.source,
+    ...policy
   };
 }
 async function publicSettings(strapi) {
@@ -242,6 +264,16 @@ async function patchStoredSettings(strapi, body) {
     next.region = region || "eu1";
   }
   if ("defaultFormId" in body) next.defaultFormId = String(body.defaultFormId ?? "").trim();
+  if ("submissionMode" in body) {
+    const mode = asSubmissionMode(body.submissionMode);
+    if (mode) next.submissionMode = mode;
+  }
+  if ("writeExtraProperties" in body && typeof body.writeExtraProperties === "boolean") {
+    next.writeExtraProperties = body.writeExtraProperties;
+  }
+  if ("syncFieldsOnPublish" in body && typeof body.syncFieldsOnPublish === "boolean") {
+    next.syncFieldsOnPublish = body.syncFieldsOnPublish;
+  }
   await setStoredSettings(strapi, next);
 }
 async function clearStoredApiKey(strapi) {
@@ -1523,6 +1555,96 @@ function resolveSubmission(definition, rawValues) {
   const unknown = Object.keys(rawValues).filter((key) => !declared.has(key));
   return { values, hidden, missingRequired, unknown };
 }
+const OBJECT_TYPE_ID = {
+  contact: "0-1",
+  company: "0-2"
+};
+function leftoverContactProps(contact, sentFieldNames) {
+  const sent = new Set(sentFieldNames);
+  const extra = {};
+  for (const [key, value] of Object.entries(contact)) {
+    if (key === "email" || sent.has(key) || value === "") continue;
+    extra[key] = value;
+  }
+  return extra;
+}
+function mappedContactFields(definition) {
+  const out = [];
+  for (const step of definition.steps ?? []) {
+    for (const fld of step.fields ?? []) {
+      if (fld.type === "company") continue;
+      const mapping = fld.hubspot ?? {};
+      const object = mapping.object?.trim() || "contact";
+      if (object !== "contact") continue;
+      const property = mapping.property?.trim() || fld.name;
+      if (!property) continue;
+      out.push({
+        name: fld.name,
+        label: typeof fld.label === "string" ? fld.label : void 0,
+        type: fld.type,
+        required: Boolean(fld.required),
+        object,
+        property,
+        options: fld.options
+      });
+    }
+  }
+  return out;
+}
+function missingMappedFields(definition, existingNames) {
+  const existing = new Set(existingNames);
+  return mappedContactFields(definition).filter((field) => !existing.has(field.property));
+}
+function hsFieldType(type, options) {
+  switch (type) {
+    case "email":
+      return "email";
+    case "tel":
+      return "phone";
+    case "textarea":
+      return "multi_line_text";
+    case "number":
+      return "number";
+    case "select":
+      return "dropdown";
+    case "radio":
+      return "radio";
+    case "checkbox":
+      return Array.isArray(options) && options.length ? "multiple_checkboxes" : "booleancheckbox";
+    default:
+      return "single_line_text";
+  }
+}
+function toHsFormField(field) {
+  const options = (field.options ?? []).filter((option) => option.value).map((option) => ({
+    value: String(option.value),
+    label: option.label || String(option.value)
+  }));
+  return {
+    objectTypeId: OBJECT_TYPE_ID[field.object || "contact"] || "0-1",
+    name: field.property,
+    label: field.label || field.property,
+    required: Boolean(field.required),
+    hidden: false,
+    fieldType: hsFieldType(field.type, field.options),
+    ...options.length ? { options } : {}
+  };
+}
+function appendFieldGroups(existing, extra) {
+  return [
+    ...existing.map((group) => ({
+      groupType: group.groupType || "default_group",
+      richTextType: group.richTextType || "text",
+      ...group.richText ? { richText: group.richText } : {},
+      fields: group.fields ?? []
+    })),
+    ...extra.map((field) => ({
+      groupType: "default_group",
+      richTextType: "text",
+      fields: [toHsFormField(field)]
+    }))
+  ];
+}
 const HS_BASE$2 = "https://api.hubapi.com";
 const OBJECT_BY_TYPE_ID = {
   "0-1": "contact",
@@ -1686,6 +1808,23 @@ async function listHubspotForms(apiKey) {
 async function fetchHubspotForm(apiKey, formId) {
   return hsGet(apiKey, `/marketing/v3/forms/${encodeURIComponent(formId)}`);
 }
+async function patchHubspotForm(apiKey, formId, body) {
+  const res = await fetch(`${HS_BASE$2}/marketing/v3/forms/${encodeURIComponent(formId)}`, {
+    method: "PATCH",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const payload = await res.json().catch(() => ({}));
+    throw Object.assign(new Error(payload.message || `HubSpot ${res.status}`), {
+      status: res.status
+    });
+  }
+  return await res.json();
+}
 const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const PORTAL = /^\d{1,12}$/;
 const HUTK = /^[a-f0-9]{8,128}$/i;
@@ -1734,6 +1873,10 @@ function formFieldNames(raw) {
   return names;
 }
 const shapeCache = /* @__PURE__ */ new Map();
+function clearFormShapeCache(formGuid) {
+  if (formGuid) shapeCache.delete(formGuid);
+  else shapeCache.clear();
+}
 async function loadFormShape(apiKey, formGuid) {
   const cached = shapeCache.get(formGuid);
   if (cached && Date.now() - cached.at < SHAPE_TTL_MS) {
@@ -1829,6 +1972,16 @@ async function submitMarketingForm(input) {
   }
   return result;
 }
+async function syncFieldsToHubspotForm(apiKey, formGuid, definition) {
+  const raw = await fetchHubspotForm(apiKey, formGuid);
+  const extra = missingMappedFields(definition, formFieldNames(raw));
+  if (!extra.length) return [];
+  await patchHubspotForm(apiKey, formGuid, {
+    fieldGroups: appendFieldGroups(raw.fieldGroups ?? [], extra)
+  });
+  clearFormShapeCache(formGuid);
+  return extra.map((field) => field.property);
+}
 function publicForm(entry) {
   return {
     slug: entry.slug,
@@ -2196,6 +2349,7 @@ function createFormsService(strapi, _opts = {}) {
       }
     }
     let usedFormsApi = false;
+    let sentFieldNames = [];
     if (email && apiKey) {
       const groups = groupByObject(form.definition, resolution.values);
       for (const [object, props] of Object.entries(companyGroups)) {
@@ -2203,21 +2357,25 @@ function createFormsService(strapi, _opts = {}) {
       }
       const partition = await partitionBySchema(apiKey, groups);
       rejected = partition.rejected;
+      const contactProps = stringProps(partition.accepted.contact ?? {});
       const account = await resolveAccount(strapi);
+      const policy = await resolvePolicy(strapi);
       const portalId = sanitizePortalId(account.portalId);
       const region = account.region || "eu1";
       const ownGuid = typeof form.hubspotFormId === "string" ? form.hubspotFormId.trim() : "";
       const formGuid = isFormGuid(ownGuid) ? ownGuid : isFormGuid(account.defaultFormId) ? account.defaultFormId.trim() : "";
-      if (portalId && formGuid) {
+      const tryFormsApi = policy.submissionMode !== "crm" && Boolean(portalId && formGuid);
+      if (tryFormsApi && portalId && formGuid) {
         try {
           const shape = await loadFormShape(apiKey, formGuid);
           const fields = filterToFormFields(
-            toHsFields({ ...stringProps(partition.accepted.contact ?? {}), email }),
+            toHsFields({ ...contactProps, email }),
             shape?.names ?? null
           );
           if (fields.length && !fields.some((f) => f.name === "email")) {
             fields.unshift({ name: "email", value: email });
           }
+          sentFieldNames = fields.map((f) => f.name);
           const submitted = await submitMarketingForm({
             apiKey,
             portalId,
@@ -2254,12 +2412,28 @@ function createFormsService(strapi, _opts = {}) {
         const result = await strapi.plugin("hubspot").service("submit").upsert({
           object: "contact",
           idProperty: "email",
-          properties: { ...partition.accepted.contact ?? {}, email }
+          properties: { ...contactProps, email }
         });
         if (result.ok) {
           hubspotSynced = true;
           contactId = result.id;
         }
+      } else if (policy.writeExtraProperties) {
+        const extra = leftoverContactProps(contactProps, sentFieldNames);
+        if (Object.keys(extra).length) {
+          try {
+            const result = await strapi.plugin("hubspot").service("submit").upsert({
+              object: "contact",
+              idProperty: "email",
+              properties: { ...extra, email }
+            });
+            if (result.ok) contactId = result.id ?? contactId;
+          } catch (err) {
+            strapi.log.warn(
+              `[hubspot] leftover contact properties failed (conversion OK) — ${err.message}`
+            );
+          }
+        }
       }
       const domain = corporateDomain(email);
       const companyProps = partition.accepted.company ?? {};
@@ -2558,7 +2732,32 @@ function createFormsAdminController(strapi) {
         documentId: ctx.params.documentId,
         locale: ctx.query.locale
       });
-      ctx.body = { ok: true };
+      const policy = await resolvePolicy(strapi);
+      let addedFields = [];
+      let syncWarning;
+      if (policy.syncFieldsOnPublish) {
+        const { apiKey } = await resolveApiKey(strapi);
+        const account = await resolveAccount(strapi);
+        const ownGuid = typeof entry.hubspotFormId === "string" ? entry.hubspotFormId.trim() : "";
+        const formGuid = isFormGuid(ownGuid) ? ownGuid : isFormGuid(account.defaultFormId) ? account.defaultFormId.trim() : "";
+        if (apiKey && formGuid) {
+          try {
+            addedFields = await syncFieldsToHubspotForm(
+              apiKey,
+              formGuid,
+              entry.definition ?? EMPTY_DEFINITION
+            );
+          } catch (err) {
+            syncWarning = err.message;
+            strapi.log.warn(`[hubspot] field sync on publish failed — ${syncWarning}`);
+          }
+        }
+      }
+      ctx.body = {
+        ok: true,
+        ...addedFields.length ? { addedFields } : {},
+        ...syncWarning ? { syncWarning } : {}
+      };
     },
     async unpublish(ctx) {
       await documents().unpublish({
@@ -3022,10 +3221,20 @@ const config = {
     //    submissions go through the marketing Forms API);
     //  - defaultFormId: portal-wide marketing form GUID when a builder form
     //    doesn't set its own — swap with the portal at production cutover.
+    //  - submissionMode / writeExtraProperties / syncFieldsOnPublish: see
+    //    Settings → HubSpot; each install picks its HubSpot will.
     forms: {
       companyFromDomain: true,
       timelineNote: true,
       defaultFormId: "",
+      // How submissions reach HubSpot. `auto` = Forms API when a GUID is set,
+      // else CRM upsert. `crm` skips conversions. `forms` prefers the Forms API.
+      submissionMode: "auto",
+      // After a conversion, CRM-write mapped contact props the HubSpot form dropped.
+      writeExtraProperties: true,
+      // On publish, PATCH missing mapped contact fields onto the HubSpot form.
+      // Off by default: HubSpot-first installs must not have Strapi mutate forms.
+      syncFieldsOnPublish: false,
       // Per-IP brakes on the public routes; 0 disables one.
       rateLimit: { submitPerMinute: 6, searchPerMinute: 30 }
     }

package/dist/server/src/__tests__/formSync.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/src/formSync.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Policy helpers for HubSpot form field sync and leftover CRM writes.
+ *
+ * Two independent user wills, neither assumed:
+ *  - Strapi-first: mapped contact fields missing on the HubSpot form can be
+ *    PATCHed onto it at publish time (opt-in).
+ *  - HubSpot-first: extras must not 400 the Forms API submit, but they can
+ *    still land on the contact via a CRM upsert of the leftovers.
+ *
+ * CRM properties are never created here — the picker only maps to ones that
+ * already exist on the portal.
+ */
+import type { FormDefinition } from "./conditions";
+export interface MappedFormField {
+    name: string;
+    label?: string;
+    type: string;
+    required?: boolean;
+    object?: string;
+    property: string;
+    options?: {
+        value?: string;
+        label?: string;
+    }[];
+}
+export declare function leftoverContactProps(contact: Record<string, string>, sentFieldNames: Iterable<string>): Record<string, string>;
+export declare function mappedContactFields(definition: FormDefinition): MappedFormField[];
+export declare function missingMappedFields(definition: FormDefinition, existingNames: Iterable<string>): MappedFormField[];
+export declare function hsFieldType(type: string, options?: unknown[]): string;
+export declare function toHsFormField(field: MappedFormField): Record<string, unknown>;
+export interface RawFieldGroupLike {
+    groupType?: string;
+    richTextType?: string;
+    richText?: string;
+    fields?: unknown[];
+}
+export declare function appendFieldGroups(existing: RawFieldGroupLike[], extra: MappedFormField[]): Record<string, unknown>[];

package/dist/server/src/forms.d.ts

@@ -2,14 +2,12 @@
  * The form-builder server side: shaping a published form for the public API,
  * and turning a submission into a HubSpot marketing-form conversion.
  *
- * The pipeline: post the answers to HubSpot's Forms API (native conversion,
- * workflows, original source, lead-center notifications) with the visitor's
- * `hutk`; look the contact back up by email; when the email is on a corporate
- * domain the company is found-or-created by `domain` and associated. A CRM
- * contact upsert is the fallback when no form GUID is configured — it does
- * not count as a form conversion. Timeline notes are opt-in and only used
- * on that fallback. Company sync is best-effort; the form submission is
- * the lead.
+ * The pipeline is a policy the install picks in Settings: native Forms API
+ * conversion (with leftover CRM writes for mapped fields the HubSpot form
+ * dropped), CRM upsert only, or automatic (Forms API when a GUID is linked).
+ * Company find-or-create still runs after a successful submit. Timeline notes
+ * are opt-in and only used on the CRM-upsert path. The form submission is
+ * the lead — a CRM outage never loses it.
  */
 import type { Core } from "@strapi/strapi";
 import { type FormDefinition, type Primitive } from "./conditions";

package/dist/server/src/hsforms.d.ts

@@ -10,6 +10,7 @@
  * Portal id, region and form GUIDs are configuration — a test portal today,
  * production tomorrow, no code change.
  */
+import type { FormDefinition } from "./conditions";
 export declare function isFormGuid(value: string): boolean;
 export declare function sanitizeHutk(value: unknown): string | undefined;
 export declare function sanitizePortalId(value: unknown): string | undefined;
@@ -58,6 +59,7 @@ export interface FormSubmitInput {
     };
     formHasLegalConsent?: boolean;
 }
+export declare function clearFormShapeCache(formGuid?: string): void;
 export declare function loadFormShape(apiKey: string, formGuid: string): Promise<{
     names: Set<string>;
     hasLegalConsent: boolean;
@@ -73,3 +75,9 @@ export declare function submitMarketingForm(input: FormSubmitInput): Promise<{
     status: number;
     error?: string;
 }>;
+/**
+ * Opt-in: add mapped contact fields that the HubSpot form doesn't already
+ * declare. Never creates CRM properties — only form fields pointing at ones
+ * that already exist. Returns the property names that were added.
+ */
+export declare function syncFieldsToHubspotForm(apiKey: string, formGuid: string, definition: FormDefinition): Promise<string[]>;

package/dist/server/src/importHubspot.d.ts

@@ -83,4 +83,8 @@ export declare function convertHubspotForm(raw: RawHubspotForm): ConvertedHubspo
 export declare function listHubspotForms(apiKey: string): Promise<HubspotFormSummary[]>;
 /** One form, full definition. */
 export declare function fetchHubspotForm(apiKey: string, formId: string): Promise<RawHubspotForm>;
+/** Replace `fieldGroups` (HubSpot PATCH is a full replacement of that array). */
+export declare function patchHubspotForm(apiKey: string, formId: string, body: {
+    fieldGroups: unknown[];
+}): Promise<RawHubspotForm>;
 export {};

package/dist/server/src/index.d.ts

@@ -13,6 +13,9 @@ declare const _default: {
                 companyFromDomain: boolean;
                 timelineNote: boolean;
                 defaultFormId: string;
+                submissionMode: "auto" | "crm" | "forms";
+                writeExtraProperties: boolean;
+                syncFieldsOnPublish: boolean;
                 rateLimit: {
                     submitPerMinute: number;
                     searchPerMinute: number;
@@ -364,6 +367,9 @@ declare const _default: {
                         portalId?: string;
                         region?: string;
                         defaultFormId?: string;
+                        submissionMode?: string;
+                        writeExtraProperties?: boolean;
+                        syncFieldsOnPublish?: boolean;
                     };
                 };
                 body: unknown;

package/dist/server/src/settings.d.ts

@@ -15,11 +15,23 @@ export declare const ENV_PORTAL = "HUBSPOT_PORTAL_ID";
 export declare const ENV_REGION = "HUBSPOT_REGION";
 export declare const ENV_DEFAULT_FORM = "HUBSPOT_DEFAULT_FORM_ID";
 export type SettingSource = "settings" | "config" | "env" | null;
+export type SubmissionMode = "auto" | "crm" | "forms";
 export interface StoredSettings {
     apiKey?: string;
     portalId?: string;
     region?: string;
     defaultFormId?: string;
+    submissionMode?: SubmissionMode;
+    writeExtraProperties?: boolean;
+    syncFieldsOnPublish?: boolean;
+}
+export interface HubspotPolicy {
+    /** How submissions reach HubSpot. `auto` uses Forms API when a GUID is set. */
+    submissionMode: SubmissionMode;
+    /** After a Forms API conversion, CRM-write mapped contact props the form dropped. */
+    writeExtraProperties: boolean;
+    /** On publish, PATCH missing mapped contact fields onto the HubSpot form. */
+    syncFieldsOnPublish: boolean;
 }
 export interface PublicSettings {
     configured: boolean;
@@ -33,6 +45,9 @@ export interface PublicSettings {
     portalSource: SettingSource;
     regionSource: SettingSource;
     formSource: SettingSource;
+    submissionMode: SubmissionMode;
+    writeExtraProperties: boolean;
+    syncFieldsOnPublish: boolean;
 }
 export interface HubspotAccount {
     portalId: string;
@@ -41,6 +56,15 @@ export interface HubspotAccount {
 }
 export declare function getStoredSettings(strapi: Core.Strapi): Promise<StoredSettings>;
 export declare function setStoredSettings(strapi: Core.Strapi, value: StoredSettings | null): Promise<void>;
+export declare function asSubmissionMode(value: unknown): SubmissionMode | undefined;
+interface FormsCfg {
+    defaultFormId?: string;
+    submissionMode?: unknown;
+    writeExtraProperties?: unknown;
+    syncFieldsOnPublish?: unknown;
+}
+export declare function policyFrom(stored: StoredSettings, forms: FormsCfg): HubspotPolicy;
+export declare function resolvePolicy(strapi: Core.Strapi): Promise<HubspotPolicy>;
 export declare function resolveApiKey(strapi: Core.Strapi): Promise<{
     apiKey: string;
     source: SettingSource;
@@ -48,12 +72,17 @@ export declare function resolveApiKey(strapi: Core.Strapi): Promise<{
 /** Portal / region / default marketing form — settings UI overrides env. */
 export declare function resolveAccount(strapi: Core.Strapi): Promise<HubspotAccount>;
 export declare function publicSettings(strapi: Core.Strapi): Promise<PublicSettings>;
-/** Merge a PATCH-like body into the store without dropping the saved key. */
-export declare function patchStoredSettings(strapi: Core.Strapi, body: {
+export interface SettingsPatch {
     apiKey?: string;
     portalId?: unknown;
     region?: unknown;
     defaultFormId?: unknown;
-}): Promise<void>;
+    submissionMode?: unknown;
+    writeExtraProperties?: unknown;
+    syncFieldsOnPublish?: unknown;
+}
+/** Merge a PATCH-like body into the store without dropping the saved key. */
+export declare function patchStoredSettings(strapi: Core.Strapi, body: SettingsPatch): Promise<void>;
 /** Drop only the stored token; portal / form settings stay. */
 export declare function clearStoredApiKey(strapi: Core.Strapi): Promise<void>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strapi-plugin-hubspot",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "The form builder for HubSpot in Strapi — multi-step forms with conditional fields mapped to real CRM properties, a public submit pipeline with retries, and save-time mapping validation.",
   "keywords": [
     "strapi",