strapi-plugin-hubspot 0.16.3 → 0.16.7

package/dist/server/index.js

@@ -1923,10 +1923,6 @@ function formsSubmitUrl(portalId, formGuid, region = "eu1") {
 function toHsFields(props) {
   return Object.entries(props).filter(([, value]) => value !== "").map(([name, value]) => ({ name, value }));
 }
-function filterToFormFields(fields, allowed) {
-  if (!allowed) return fields;
-  return fields.filter((field) => allowed.has(field.name));
-}
 function formFieldNames(raw) {
   const names = [];
   for (const group of raw.fieldGroups ?? []) {
@@ -1936,6 +1932,103 @@ function formFieldNames(raw) {
   }
   return names;
 }
+const OBJECT_BAG = {
+  "0-1": "contact",
+  "0-2": "company"
+};
+function formShapeFields(raw) {
+  const fields = [];
+  for (const group of raw.fieldGroups ?? []) {
+    for (const field of group.fields ?? []) {
+      if (!field.name) continue;
+      fields.push({
+        name: field.name,
+        objectTypeId: field.objectTypeId?.trim() || "0-1",
+        required: Boolean(field.required)
+      });
+    }
+  }
+  return fields;
+}
+function fieldsForHubspotForm(bags, shape, extra = {}) {
+  const contact = { ...bags.contact ?? {}, ...extra };
+  if (!shape?.fields.length) {
+    return toHsFields(contact).map((field) => ({ ...field, objectTypeId: "0-1" }));
+  }
+  const out = [];
+  for (const field of shape.fields) {
+    const bagName = OBJECT_BAG[field.objectTypeId] || "contact";
+    const value = bags[bagName]?.[field.name] ?? contact[field.name];
+    if (!value) continue;
+    out.push({ name: field.name, value, objectTypeId: field.objectTypeId || "0-1" });
+  }
+  return out;
+}
+function parseFormShape(raw) {
+  const legal = raw.legalConsentOptions;
+  const legalType = typeof legal?.type === "string" ? legal.type : void 0;
+  const hasLegalConsent = Boolean(legalType && legalType !== "none");
+  const communications = [];
+  for (const box of legal?.communicationsCheckboxes ?? []) {
+    const id = Number(box.subscriptionTypeId ?? box.communicationTypeId);
+    if (!Number.isFinite(id) || id <= 0) continue;
+    communications.push({
+      subscriptionTypeId: id,
+      text: String(box.label || box.text || "").trim() || "I agree to receive communications."
+    });
+  }
+  const subscriptionTypeIds = (legal?.subscriptionTypeIds ?? []).map((id) => Number(id)).filter((id) => Number.isFinite(id) && id > 0);
+  const consentToProcessText = legal?.consentToProcessText?.trim();
+  const privacyText = legal?.privacyText?.trim();
+  const lawfulRaw = String(legal?.lawfulBasis || "").toUpperCase();
+  const fields = formShapeFields(raw);
+  return {
+    names: new Set(fields.map((field) => field.name)),
+    required: new Set(fields.filter((field) => field.required).map((field) => field.name)),
+    fields,
+    hasLegalConsent,
+    ...legalType ? { legalType } : {},
+    lawfulBasis: lawfulRaw.includes("CUSTOMER") ? "CUSTOMER" : "LEAD",
+    subscriptionTypeIds,
+    ...privacyText ? { privacyText } : {},
+    captcha: raw.configuration?.recaptchaEnabled === true || raw.configuration?.captchaEnabled === true,
+    ...consentToProcessText ? { consentToProcessText } : {},
+    communications
+  };
+}
+function canRetryEmailOnly(required) {
+  const names = [...required ?? []];
+  return names.length === 0 || names.every((name) => name === "email");
+}
+function buildLegalConsent(shape, given, fallbackText) {
+  if (!given) return void 0;
+  if (shape && !shape.hasLegalConsent) return void 0;
+  const fallback = fallbackText?.trim() || DEFAULT_CONSENT_TEXT;
+  if (shape?.legalType === "legitimate_interest") {
+    const subscriptionTypeId = shape.subscriptionTypeIds[0];
+    if (!subscriptionTypeId) return void 0;
+    return {
+      legitimateInterest: {
+        value: true,
+        subscriptionTypeId,
+        legalBasis: shape.lawfulBasis || "LEAD",
+        text: shape.privacyText?.trim() || fallback
+      }
+    };
+  }
+  const consent = {
+    consentToProcess: true,
+    text: shape?.consentToProcessText?.trim() || fallback
+  };
+  if (shape?.communications.length) {
+    consent.communications = shape.communications.map((item) => ({
+      value: true,
+      subscriptionTypeId: item.subscriptionTypeId,
+      text: item.text
+    }));
+  }
+  return { consent };
+}
 const shapeCache = /* @__PURE__ */ new Map();
 function clearFormShapeCache(formGuid) {
   if (formGuid) shapeCache.delete(formGuid);
@@ -1944,16 +2037,13 @@ function clearFormShapeCache(formGuid) {
 async function loadFormShape(apiKey, formGuid) {
   const cached = shapeCache.get(formGuid);
   if (cached && Date.now() - cached.at < SHAPE_TTL_MS) {
-    return { names: cached.names, hasLegalConsent: cached.hasLegalConsent };
+    return cached.shape;
   }
   try {
     const raw = await fetchHubspotForm(apiKey, formGuid);
-    const names = new Set(formFieldNames(raw));
-    const hasLegalConsent = Boolean(
-      raw.legalConsentOptions && typeof raw.legalConsentOptions === "object" && raw.legalConsentOptions.type && raw.legalConsentOptions.type !== "none"
-    );
-    shapeCache.set(formGuid, { at: Date.now(), names, hasLegalConsent });
-    return { names, hasLegalConsent };
+    const shape = parseFormShape(raw);
+    shapeCache.set(formGuid, { at: Date.now(), shape });
+    return shape;
   } catch {
     return null;
   }
@@ -2011,28 +2101,45 @@ async function submitMarketingForm(input) {
   if (!portalId || !isFormGuid(formGuid) || !input.fields.length) {
     return { ok: false, status: 0, error: "Missing portal, form GUID or fields" };
   }
+  if (input.shape?.captcha) {
+    return {
+      ok: false,
+      status: 0,
+      error: "HubSpot form has CAPTCHA enabled — the Forms API cannot submit it. Turn CAPTCHA off on that marketing form."
+    };
+  }
   const url = formsSubmitUrl(portalId, formGuid, input.region);
   const context = contextPayload(input.context);
+  const fields = input.fields.map((field) => ({
+    objectTypeId: field.objectTypeId || "0-1",
+    name: field.name,
+    value: field.value
+  }));
   const base = {
-    fields: input.fields,
+    fields,
     ...Object.keys(context).length ? { context } : {}
   };
-  const withConsent = input.consent?.given && input.formHasLegalConsent !== false ? {
-    ...base,
-    legalConsentOptions: {
-      consent: {
-        consentToProcess: true,
-        text: input.consent.text?.trim() || DEFAULT_CONSENT_TEXT
-      }
-    }
-  } : base;
+  const legal = buildLegalConsent(
+    input.shape,
+    input.consent?.given === true,
+    input.consent?.text
+  );
+  const withConsent = legal ? { ...base, legalConsentOptions: legal } : base;
   let result = await postForm(url, input.apiKey, withConsent);
-  if (!result.ok && result.status === 400 && withConsent !== base) {
+  const mustKeepConsent = Boolean(input.shape?.hasLegalConsent && legal);
+  if (!result.ok && result.status === 400 && withConsent !== base && !mustKeepConsent) {
     result = await postForm(url, input.apiKey, base);
   }
-  if (!result.ok && result.status === 400 && input.fields.length > 1) {
-    const email = input.fields.find((f) => f.name === "email");
-    if (email) result = await postForm(url, input.apiKey, { ...base, fields: [email] });
+  if (!result.ok && result.status === 400 && input.fields.length > 1 && canRetryEmailOnly(input.shape?.required)) {
+    const email = fields.find((f) => f.name === "email");
+    if (email) {
+      const slim = { ...base, fields: [email] };
+      result = await postForm(
+        url,
+        input.apiKey,
+        legal && mustKeepConsent ? { ...slim, legalConsentOptions: legal } : slim
+      );
+    }
   }
   return result;
 }
@@ -2414,6 +2521,7 @@ function createFormsService(strapi, _opts = {}) {
     }
     let usedFormsApi = false;
     let sentFieldNames = [];
+    let conversionError;
     if (email && apiKey) {
       const groups = groupByObject(form.definition, resolution.values);
       for (const [object, props] of Object.entries(companyGroups)) {
@@ -2432,12 +2540,16 @@ function createFormsService(strapi, _opts = {}) {
       if (tryFormsApi && portalId && formGuid) {
         try {
           const shape = await loadFormShape(apiKey, formGuid);
-          const fields = filterToFormFields(
-            toHsFields({ ...contactProps, email }),
-            shape?.names ?? null
+          const fields = fieldsForHubspotForm(
+            {
+              contact: contactProps,
+              company: stringProps(partition.accepted.company ?? {})
+            },
+            shape,
+            { email }
           );
           if (fields.length && !fields.some((f) => f.name === "email")) {
-            fields.unshift({ name: "email", value: email });
+            fields.unshift({ name: "email", value: email, objectTypeId: "0-1" });
           }
           sentFieldNames = fields.map((f) => f.name);
           const submitted = await submitMarketingForm({
@@ -2445,7 +2557,7 @@ function createFormsService(strapi, _opts = {}) {
             portalId,
             formGuid,
             region,
-            fields: fields.length ? fields : [{ name: "email", value: email }],
+            fields: fields.length ? fields : [{ name: "email", value: email, objectTypeId: "0-1" }],
             context: {
               hutk: sanitizeHutk(meta.hutk),
               pageUri: typeof meta.pageUrl === "string" ? meta.pageUrl : void 0,
@@ -2453,7 +2565,7 @@ function createFormsService(strapi, _opts = {}) {
               ipAddress: sanitizeIp(meta.ipAddress)
             },
             consent: { given: meta.consent === true },
-            formHasLegalConsent: shape?.hasLegalConsent
+            shape
           });
           if (submitted.ok) {
             hubspotSynced = true;
@@ -2466,10 +2578,12 @@ function createFormsService(strapi, _opts = {}) {
               );
             }
           } else {
+            conversionError = submitted.error;
             strapi.log.warn(`[hubspot] Forms API submit failed — ${submitted.error}`);
           }
         } catch (err) {
-          strapi.log.warn(`[hubspot] Forms API submit failed — ${err.message}`);
+          conversionError = err.message;
+          strapi.log.warn(`[hubspot] Forms API submit failed — ${conversionError}`);
         }
       }
       if (!usedFormsApi) {
@@ -2551,7 +2665,11 @@ function createFormsService(strapi, _opts = {}) {
         formTitle: form.title || form.name,
         email,
         values: resolution.values,
-        meta,
+        meta: {
+          ...meta,
+          hubspotConversion: usedFormsApi,
+          ...conversionError ? { hubspotError: conversionError } : {}
+        },
         locale: form.locale ?? null,
         hubspotSynced,
         contactId,
@@ -2738,7 +2856,7 @@ function createFormsAdminController(strapi) {
         locale: ctx.query.locale,
         status: "published"
       });
-      ctx.body = { form: entry, published: Boolean(published) };
+      ctx.body = { form: entry, published: Boolean(published), publishedHubspotFormId: published?.hubspotFormId ?? null };
     },
     async create(ctx) {
       const body = ctx.request.body ?? {};

package/dist/server/index.mjs

@@ -1922,10 +1922,6 @@ function formsSubmitUrl(portalId, formGuid, region = "eu1") {
 function toHsFields(props) {
   return Object.entries(props).filter(([, value]) => value !== "").map(([name, value]) => ({ name, value }));
 }
-function filterToFormFields(fields, allowed) {
-  if (!allowed) return fields;
-  return fields.filter((field) => allowed.has(field.name));
-}
 function formFieldNames(raw) {
   const names = [];
   for (const group of raw.fieldGroups ?? []) {
@@ -1935,6 +1931,103 @@ function formFieldNames(raw) {
   }
   return names;
 }
+const OBJECT_BAG = {
+  "0-1": "contact",
+  "0-2": "company"
+};
+function formShapeFields(raw) {
+  const fields = [];
+  for (const group of raw.fieldGroups ?? []) {
+    for (const field of group.fields ?? []) {
+      if (!field.name) continue;
+      fields.push({
+        name: field.name,
+        objectTypeId: field.objectTypeId?.trim() || "0-1",
+        required: Boolean(field.required)
+      });
+    }
+  }
+  return fields;
+}
+function fieldsForHubspotForm(bags, shape, extra = {}) {
+  const contact = { ...bags.contact ?? {}, ...extra };
+  if (!shape?.fields.length) {
+    return toHsFields(contact).map((field) => ({ ...field, objectTypeId: "0-1" }));
+  }
+  const out = [];
+  for (const field of shape.fields) {
+    const bagName = OBJECT_BAG[field.objectTypeId] || "contact";
+    const value = bags[bagName]?.[field.name] ?? contact[field.name];
+    if (!value) continue;
+    out.push({ name: field.name, value, objectTypeId: field.objectTypeId || "0-1" });
+  }
+  return out;
+}
+function parseFormShape(raw) {
+  const legal = raw.legalConsentOptions;
+  const legalType = typeof legal?.type === "string" ? legal.type : void 0;
+  const hasLegalConsent = Boolean(legalType && legalType !== "none");
+  const communications = [];
+  for (const box of legal?.communicationsCheckboxes ?? []) {
+    const id = Number(box.subscriptionTypeId ?? box.communicationTypeId);
+    if (!Number.isFinite(id) || id <= 0) continue;
+    communications.push({
+      subscriptionTypeId: id,
+      text: String(box.label || box.text || "").trim() || "I agree to receive communications."
+    });
+  }
+  const subscriptionTypeIds = (legal?.subscriptionTypeIds ?? []).map((id) => Number(id)).filter((id) => Number.isFinite(id) && id > 0);
+  const consentToProcessText = legal?.consentToProcessText?.trim();
+  const privacyText = legal?.privacyText?.trim();
+  const lawfulRaw = String(legal?.lawfulBasis || "").toUpperCase();
+  const fields = formShapeFields(raw);
+  return {
+    names: new Set(fields.map((field) => field.name)),
+    required: new Set(fields.filter((field) => field.required).map((field) => field.name)),
+    fields,
+    hasLegalConsent,
+    ...legalType ? { legalType } : {},
+    lawfulBasis: lawfulRaw.includes("CUSTOMER") ? "CUSTOMER" : "LEAD",
+    subscriptionTypeIds,
+    ...privacyText ? { privacyText } : {},
+    captcha: raw.configuration?.recaptchaEnabled === true || raw.configuration?.captchaEnabled === true,
+    ...consentToProcessText ? { consentToProcessText } : {},
+    communications
+  };
+}
+function canRetryEmailOnly(required) {
+  const names = [...required ?? []];
+  return names.length === 0 || names.every((name) => name === "email");
+}
+function buildLegalConsent(shape, given, fallbackText) {
+  if (!given) return void 0;
+  if (shape && !shape.hasLegalConsent) return void 0;
+  const fallback = fallbackText?.trim() || DEFAULT_CONSENT_TEXT;
+  if (shape?.legalType === "legitimate_interest") {
+    const subscriptionTypeId = shape.subscriptionTypeIds[0];
+    if (!subscriptionTypeId) return void 0;
+    return {
+      legitimateInterest: {
+        value: true,
+        subscriptionTypeId,
+        legalBasis: shape.lawfulBasis || "LEAD",
+        text: shape.privacyText?.trim() || fallback
+      }
+    };
+  }
+  const consent = {
+    consentToProcess: true,
+    text: shape?.consentToProcessText?.trim() || fallback
+  };
+  if (shape?.communications.length) {
+    consent.communications = shape.communications.map((item) => ({
+      value: true,
+      subscriptionTypeId: item.subscriptionTypeId,
+      text: item.text
+    }));
+  }
+  return { consent };
+}
 const shapeCache = /* @__PURE__ */ new Map();
 function clearFormShapeCache(formGuid) {
   if (formGuid) shapeCache.delete(formGuid);
@@ -1943,16 +2036,13 @@ function clearFormShapeCache(formGuid) {
 async function loadFormShape(apiKey, formGuid) {
   const cached = shapeCache.get(formGuid);
   if (cached && Date.now() - cached.at < SHAPE_TTL_MS) {
-    return { names: cached.names, hasLegalConsent: cached.hasLegalConsent };
+    return cached.shape;
   }
   try {
     const raw = await fetchHubspotForm(apiKey, formGuid);
-    const names = new Set(formFieldNames(raw));
-    const hasLegalConsent = Boolean(
-      raw.legalConsentOptions && typeof raw.legalConsentOptions === "object" && raw.legalConsentOptions.type && raw.legalConsentOptions.type !== "none"
-    );
-    shapeCache.set(formGuid, { at: Date.now(), names, hasLegalConsent });
-    return { names, hasLegalConsent };
+    const shape = parseFormShape(raw);
+    shapeCache.set(formGuid, { at: Date.now(), shape });
+    return shape;
   } catch {
     return null;
   }
@@ -2010,28 +2100,45 @@ async function submitMarketingForm(input) {
   if (!portalId || !isFormGuid(formGuid) || !input.fields.length) {
     return { ok: false, status: 0, error: "Missing portal, form GUID or fields" };
   }
+  if (input.shape?.captcha) {
+    return {
+      ok: false,
+      status: 0,
+      error: "HubSpot form has CAPTCHA enabled — the Forms API cannot submit it. Turn CAPTCHA off on that marketing form."
+    };
+  }
   const url = formsSubmitUrl(portalId, formGuid, input.region);
   const context = contextPayload(input.context);
+  const fields = input.fields.map((field) => ({
+    objectTypeId: field.objectTypeId || "0-1",
+    name: field.name,
+    value: field.value
+  }));
   const base = {
-    fields: input.fields,
+    fields,
     ...Object.keys(context).length ? { context } : {}
   };
-  const withConsent = input.consent?.given && input.formHasLegalConsent !== false ? {
-    ...base,
-    legalConsentOptions: {
-      consent: {
-        consentToProcess: true,
-        text: input.consent.text?.trim() || DEFAULT_CONSENT_TEXT
-      }
-    }
-  } : base;
+  const legal = buildLegalConsent(
+    input.shape,
+    input.consent?.given === true,
+    input.consent?.text
+  );
+  const withConsent = legal ? { ...base, legalConsentOptions: legal } : base;
   let result = await postForm(url, input.apiKey, withConsent);
-  if (!result.ok && result.status === 400 && withConsent !== base) {
+  const mustKeepConsent = Boolean(input.shape?.hasLegalConsent && legal);
+  if (!result.ok && result.status === 400 && withConsent !== base && !mustKeepConsent) {
     result = await postForm(url, input.apiKey, base);
   }
-  if (!result.ok && result.status === 400 && input.fields.length > 1) {
-    const email = input.fields.find((f) => f.name === "email");
-    if (email) result = await postForm(url, input.apiKey, { ...base, fields: [email] });
+  if (!result.ok && result.status === 400 && input.fields.length > 1 && canRetryEmailOnly(input.shape?.required)) {
+    const email = fields.find((f) => f.name === "email");
+    if (email) {
+      const slim = { ...base, fields: [email] };
+      result = await postForm(
+        url,
+        input.apiKey,
+        legal && mustKeepConsent ? { ...slim, legalConsentOptions: legal } : slim
+      );
+    }
   }
   return result;
 }
@@ -2413,6 +2520,7 @@ function createFormsService(strapi, _opts = {}) {
     }
     let usedFormsApi = false;
     let sentFieldNames = [];
+    let conversionError;
     if (email && apiKey) {
       const groups = groupByObject(form.definition, resolution.values);
       for (const [object, props] of Object.entries(companyGroups)) {
@@ -2431,12 +2539,16 @@ function createFormsService(strapi, _opts = {}) {
       if (tryFormsApi && portalId && formGuid) {
         try {
           const shape = await loadFormShape(apiKey, formGuid);
-          const fields = filterToFormFields(
-            toHsFields({ ...contactProps, email }),
-            shape?.names ?? null
+          const fields = fieldsForHubspotForm(
+            {
+              contact: contactProps,
+              company: stringProps(partition.accepted.company ?? {})
+            },
+            shape,
+            { email }
           );
           if (fields.length && !fields.some((f) => f.name === "email")) {
-            fields.unshift({ name: "email", value: email });
+            fields.unshift({ name: "email", value: email, objectTypeId: "0-1" });
           }
           sentFieldNames = fields.map((f) => f.name);
           const submitted = await submitMarketingForm({
@@ -2444,7 +2556,7 @@ function createFormsService(strapi, _opts = {}) {
             portalId,
             formGuid,
             region,
-            fields: fields.length ? fields : [{ name: "email", value: email }],
+            fields: fields.length ? fields : [{ name: "email", value: email, objectTypeId: "0-1" }],
             context: {
               hutk: sanitizeHutk(meta.hutk),
               pageUri: typeof meta.pageUrl === "string" ? meta.pageUrl : void 0,
@@ -2452,7 +2564,7 @@ function createFormsService(strapi, _opts = {}) {
               ipAddress: sanitizeIp(meta.ipAddress)
             },
             consent: { given: meta.consent === true },
-            formHasLegalConsent: shape?.hasLegalConsent
+            shape
           });
           if (submitted.ok) {
             hubspotSynced = true;
@@ -2465,10 +2577,12 @@ function createFormsService(strapi, _opts = {}) {
               );
             }
           } else {
+            conversionError = submitted.error;
             strapi.log.warn(`[hubspot] Forms API submit failed — ${submitted.error}`);
           }
         } catch (err) {
-          strapi.log.warn(`[hubspot] Forms API submit failed — ${err.message}`);
+          conversionError = err.message;
+          strapi.log.warn(`[hubspot] Forms API submit failed — ${conversionError}`);
         }
       }
       if (!usedFormsApi) {
@@ -2550,7 +2664,11 @@ function createFormsService(strapi, _opts = {}) {
         formTitle: form.title || form.name,
         email,
         values: resolution.values,
-        meta,
+        meta: {
+          ...meta,
+          hubspotConversion: usedFormsApi,
+          ...conversionError ? { hubspotError: conversionError } : {}
+        },
         locale: form.locale ?? null,
         hubspotSynced,
         contactId,
@@ -2737,7 +2855,7 @@ function createFormsAdminController(strapi) {
         locale: ctx.query.locale,
         status: "published"
       });
-      ctx.body = { form: entry, published: Boolean(published) };
+      ctx.body = { form: entry, published: Boolean(published), publishedHubspotFormId: published?.hubspotFormId ?? null };
     },
     async create(ctx) {
       const body = ctx.request.body ?? {};

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

@@ -23,20 +23,91 @@ export declare function toHsFields(props: Record<string, string>): {
     name: string;
     value: string;
 }[];
-export declare function filterToFormFields(fields: {
+export declare function filterToFormFields<T extends {
     name: string;
-    value: string;
-}[], allowed: Set<string> | null): {
+}>(fields: T[], allowed: Set<string> | null): T[];
+export declare function formFieldNames(raw: {
+    fieldGroups?: {
+        fields?: {
+            name?: string;
+            required?: boolean;
+        }[];
+    }[];
+}): string[];
+export declare function formRequiredNames(raw: {
+    fieldGroups?: {
+        fields?: {
+            name?: string;
+            required?: boolean;
+        }[];
+    }[];
+}): string[];
+export interface CommunicationConsent {
+    subscriptionTypeId: number;
+    text: string;
+}
+export interface FormShapeField {
+    name: string;
+    objectTypeId: string;
+    required: boolean;
+}
+export interface FormShape {
+    names: Set<string>;
+    required: Set<string>;
+    fields: FormShapeField[];
+    hasLegalConsent: boolean;
+    legalType?: string;
+    lawfulBasis?: "LEAD" | "CUSTOMER";
+    subscriptionTypeIds: number[];
+    privacyText?: string;
+    captcha: boolean;
+    consentToProcessText?: string;
+    communications: CommunicationConsent[];
+}
+export declare function formShapeFields(raw: {
+    fieldGroups?: {
+        fields?: {
+            name?: string;
+            required?: boolean;
+            objectTypeId?: string;
+        }[];
+    }[];
+}): FormShapeField[];
+/** Values HubSpot declared on the marketing form, with the right objectTypeId. */
+export declare function fieldsForHubspotForm(bags: Record<string, Record<string, string>>, shape: FormShape | null | undefined, extra?: Record<string, string>): {
     name: string;
     value: string;
+    objectTypeId: string;
 }[];
-export declare function formFieldNames(raw: {
+export declare function parseFormShape(raw: {
     fieldGroups?: {
         fields?: {
             name?: string;
+            required?: boolean;
+            objectTypeId?: string;
         }[];
     }[];
-}): string[];
+    configuration?: {
+        captchaEnabled?: boolean;
+        recaptchaEnabled?: boolean;
+    };
+    legalConsentOptions?: {
+        type?: string;
+        lawfulBasis?: string;
+        privacyText?: string;
+        subscriptionTypeIds?: (number | string)[];
+        consentToProcessText?: string;
+        communicationsCheckboxes?: {
+            label?: string;
+            text?: string;
+            subscriptionTypeId?: number | string;
+            communicationTypeId?: number | string;
+        }[];
+    } | null;
+}): FormShape;
+/** Email-only retry is only safe when HubSpot doesn't require other fields. */
+export declare function canRetryEmailOnly(required: Iterable<string> | undefined): boolean;
+export declare function buildLegalConsent(shape: Pick<FormShape, "hasLegalConsent" | "legalType" | "lawfulBasis" | "subscriptionTypeIds" | "privacyText" | "communications" | "consentToProcessText"> | null | undefined, given: boolean, fallbackText?: string): Record<string, unknown> | undefined;
 export interface FormSubmitContext {
     hutk?: string;
     pageUri?: string;
@@ -51,24 +122,25 @@ export interface FormSubmitInput {
     fields: {
         name: string;
         value: string;
+        objectTypeId?: string;
     }[];
     context?: FormSubmitContext;
     consent?: {
         given: boolean;
         text?: string;
     };
-    formHasLegalConsent?: boolean;
+    shape?: FormShape | null;
 }
 export declare function clearFormShapeCache(formGuid?: string): void;
-export declare function loadFormShape(apiKey: string, formGuid: string): Promise<{
-    names: Set<string>;
-    hasLegalConsent: boolean;
-} | null>;
+export declare function loadFormShape(apiKey: string, formGuid: string): Promise<FormShape | null>;
 export declare function findContactIdByEmail(apiKey: string, email: string): Promise<string | undefined>;
 /**
  * Submit a marketing form. Extra fields HubSpot doesn't know on that form
- * 400 the whole request, so callers should filter first; we still retry
- * without legal-consent and then email-only if HubSpot refuses the payload.
+ * 400 the whole request, so callers should filter first. A GDPR block on the
+ * HubSpot form needs the matching legalConsentOptions (including
+ * communications); stripping consent to "retry" would 400 forever. Email-only
+ * retry is only used when HubSpot doesn't require other fields. CAPTCHA
+ * cannot be solved server-side.
  */
 export declare function submitMarketingForm(input: FormSubmitInput): Promise<{
     ok: boolean;