strapi-plugin-hubspot 0.14.0 → 0.16.0

package/dist/server/index.mjs

@@ -158,6 +158,9 @@ function resolveObjects(configured) {
   return out;
 }
 const ENV_VAR = "HUBSPOT_API_KEY";
+const ENV_PORTAL = "HUBSPOT_PORTAL_ID";
+const ENV_REGION = "HUBSPOT_REGION";
+const ENV_DEFAULT_FORM = "HUBSPOT_DEFAULT_FORM_ID";
 const store = (strapi) => strapi.store({ type: "plugin", name: "hubspot" });
 async function getStoredSettings(strapi) {
   return await store(strapi).get({ key: "settings" }) ?? {};
@@ -166,6 +169,33 @@ async function setStoredSettings(strapi, value) {
   await store(strapi).set({ key: "settings", value });
   clearCache();
 }
+const first = (values, fallback = "") => {
+  for (const item of values) {
+    const value = (item.value ?? "").trim();
+    if (value) return { value, source: item.source };
+  }
+  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" };
@@ -175,14 +205,83 @@ async function resolveApiKey(strapi) {
   if (fromEnv) return { apiKey: fromEnv, source: "env" };
   return { apiKey: "", source: null };
 }
-async function publicSettings(strapi) {
-  const { apiKey, source } = await resolveApiKey(strapi);
+async function resolveAccount(strapi) {
+  const resolved = await resolveAccountSources(strapi);
+  return {
+    portalId: resolved.portalId,
+    region: resolved.region || "eu1",
+    defaultFormId: resolved.defaultFormId
+  };
+}
+async function resolveAccountSources(strapi) {
+  const stored = await getStoredSettings(strapi);
+  const forms = formsCfg(strapi);
+  const portal = first([
+    { value: stored.portalId, source: "settings" },
+    { value: strapi.plugin("hubspot").config("portalId", ""), source: "config" },
+    { value: process.env[ENV_PORTAL], source: "env" }
+  ]);
+  const region = first(
+    [
+      { value: stored.region, source: "settings" },
+      { value: strapi.plugin("hubspot").config("region", ""), source: "config" },
+      { value: process.env[ENV_REGION], source: "env" }
+    ],
+    "eu1"
+  );
+  const form = first([
+    { value: stored.defaultFormId, source: "settings" },
+    { 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: source,
-    hint: apiKey ? `…${apiKey.slice(-4)}` : ""
+    keySource,
+    hint: apiKey ? `…${apiKey.slice(-4)}` : "",
+    portalId: portal.value,
+    region: region.value || "eu1",
+    defaultFormId: form.value,
+    portalSource: portal.source,
+    regionSource: region.source,
+    formSource: form.source,
+    ...policy
   };
 }
+async function publicSettings(strapi) {
+  return resolveAccountSources(strapi);
+}
+async function patchStoredSettings(strapi, body) {
+  const current = await getStoredSettings(strapi);
+  const next = { ...current };
+  if (typeof body.apiKey === "string" && body.apiKey.trim()) {
+    next.apiKey = body.apiKey.trim();
+  }
+  if ("portalId" in body) next.portalId = String(body.portalId ?? "").trim();
+  if ("region" in body) {
+    const region = String(body.region ?? "").trim().toLowerCase();
+    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) {
+  const current = await getStoredSettings(strapi);
+  const { apiKey: _apiKey, ...rest } = current;
+  const empty = !rest.portalId && !rest.region && !rest.defaultFormId;
+  await setStoredSettings(strapi, empty ? null : rest);
+}
 function collectMappings(node, target, found = []) {
   if (Array.isArray(node)) {
     for (const item of node) collectMappings(item, target, found);
@@ -1456,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",
@@ -1619,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;
@@ -1667,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) {
@@ -1762,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,
@@ -2129,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)) {
@@ -2136,20 +2357,25 @@ function createFormsService(strapi, _opts = {}) {
       }
       const partition = await partitionBySchema(apiKey, groups);
       rejected = partition.rejected;
-      const portalId = sanitizePortalId(strapi.plugin("hubspot").config("portalId", ""));
-      const region = String(strapi.plugin("hubspot").config("region", "eu1") || "eu1");
+      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(config2.defaultFormId) ? config2.defaultFormId.trim() : "";
-      if (portalId && formGuid) {
+      const formGuid = isFormGuid(ownGuid) ? ownGuid : isFormGuid(account.defaultFormId) ? account.defaultFormId.trim() : "";
+      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,
@@ -2186,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 ?? {};
@@ -2490,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({
@@ -2954,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 }
     }
@@ -3140,15 +3417,24 @@ const controllers = {
   },
   settings: ({ strapi }) => ({
     async get(ctx) {
-      ctx.body = await publicSettings(strapi);
+      const settings = await publicSettings(strapi);
+      let forms = [];
+      const { apiKey } = await resolveApiKey(strapi);
+      if (apiKey) {
+        try {
+          forms = await listHubspotForms(apiKey);
+        } catch {
+          forms = [];
+        }
+      }
+      ctx.body = { ...settings, forms };
     },
     async update(ctx) {
-      const apiKey = (ctx.request.body?.apiKey ?? "").trim();
-      await setStoredSettings(strapi, apiKey ? { apiKey } : null);
+      await patchStoredSettings(strapi, ctx.request.body ?? {});
       ctx.body = await publicSettings(strapi);
     },
     async reset(ctx) {
-      await setStoredSettings(strapi, null);
+      await clearStoredApiKey(strapi);
       ctx.body = await publicSettings(strapi);
     }
   })

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

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

package/dist/server/src/__tests__/settings.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;
@@ -50,6 +53,7 @@ declare const _default: {
                 };
                 attributes: {
                     name: {
+                        /** RBAC action gating the settings screen and its routes. */
                         type: string;
                         required: boolean;
                         pluginOptions: {
@@ -358,8 +362,14 @@ declare const _default: {
             }): Promise<void>;
             update(ctx: {
                 request: {
-                    body: {
+                    body?: {
                         apiKey?: string;
+                        portalId?: string;
+                        region?: string;
+                        defaultFormId?: string;
+                        submissionMode?: string;
+                        writeExtraProperties?: boolean;
+                        syncFieldsOnPublish?: boolean;
                     };
                 };
                 body: unknown;

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

@@ -1,28 +1,88 @@
 import type { Core } from "@strapi/strapi";
 /**
- * API key resolution, in order of precedence:
+ * API key + portal resolution, in order of precedence:
  *  1. saved from the admin UI (plugin core store)
  *  2. plugin config (config/plugins of the host app)
- *  3. environment variable (HUBSPOT_API_KEY)
+ *  3. environment variable
  *
  * The key is only ever read server-side; `publicSettings` is what the admin UI
- * receives, and it deliberately never carries the key itself.
+ * receives, and it deliberately never carries the key itself. Portal id, region
+ * and the default form GUID are not secrets — they round-trip so they can be
+ * edited in Settings → HubSpot.
  */
 export declare const ENV_VAR = "HUBSPOT_API_KEY";
+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;
     /** Where the key comes from, so the UI can explain why it can't be edited. */
-    keySource: "settings" | "config" | "env" | null;
+    keySource: SettingSource;
     /** Last four characters, enough to recognise a key without exposing it. */
     hint: string;
+    portalId: string;
+    region: string;
+    defaultFormId: string;
+    portalSource: SettingSource;
+    regionSource: SettingSource;
+    formSource: SettingSource;
+    submissionMode: SubmissionMode;
+    writeExtraProperties: boolean;
+    syncFieldsOnPublish: boolean;
+}
+export interface HubspotAccount {
+    portalId: string;
+    region: string;
+    defaultFormId: string;
 }
 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: PublicSettings["keySource"];
+    source: SettingSource;
 }>;
+/** 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>;
+export interface SettingsPatch {
+    apiKey?: string;
+    portalId?: unknown;
+    region?: unknown;
+    defaultFormId?: unknown;
+    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.14.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",