strapi-plugin-hubspot 0.3.0 → 0.4.1

package/README.md

@@ -59,11 +59,46 @@ setting reads:
 }
 ```
 
+Once filtered, the list is ordered and prefixed by the property's **HubSpot
+group** — the portal's own way of organising hundreds of properties:
+
+```
+Informations de contact · Prénom (firstname)
+Informations de contact · Rôle (hs_role)
+Historique · Source (hs_analytics_source)
+```
+
 Read-only properties — the ones HubSpot computes and always refuses to
 accept — are filtered out, so the list only ever offers things that will
 actually work. When the portal id is readable, each selected property gets a
 **Voir dans HubSpot** link straight to its settings page.
 
+### An object picker to feed it
+
+The sibling object field doesn't have to be a hand-typed enum: the
+`hubspot.object` custom field is a select over the portal's configured
+objects. An object the token can't read stays selectable, flagged with its
+missing scope.
+
+```json
+{
+  "hsObject": {
+    "type": "customField",
+    "customField": "plugin::hubspot.object"
+  }
+}
+```
+
+### One-click option import
+
+For an **enumeration** property, the picker shows an *Import the N options
+from HubSpot* button that fills the sibling repeatable (default `options`,
+entries `{ value, label }` — the same shape the validation reads) with the
+enumeration's real choices. The `bad-option` check detects a select that
+drifted from the CRM; this is what fixes it. Point `optionsField` (in the
+field's HubSpot options, next to `objectField`) at the repeatable if it isn't
+called `options`.
+
 ### Validation on save
 
 Point the plugin at the content types that carry mappings and it walks each
@@ -91,6 +126,63 @@ each `{ value?, label? }`) and they are checked too.
 Each problem is also carried as a structured code in the error's `details`, so a
 host app can localize the message instead of parsing the sentence.
 
+**`unknown` is the one code a legitimate workflow can produce** — a property
+staged in HubSpot but not created yet. Set `strict: false` on a validate target
+and those pass with a warning in the logs instead of blocking the save. The
+other three codes always block, whatever `strict` says: no workflow produces a
+wrong object, a trailing space, or a drifted option on purpose.
+
+### An audit of existing content
+
+Save-time validation only protects entries as they are written. A property
+deleted in HubSpot afterwards leaves invalid mappings dormant in content nobody
+re-saves — until a submission silently fails. **Settings → HubSpot → Mapping
+audit** walks every entry of the validated content types (drafts, every locale,
+at any depth) against a freshly fetched schema, and lists each entry the portal
+would reject today, linking straight to it in the Content Manager.
+
+The audit reports `unknown` properties even on `strict: false` targets: strict
+only decides whether a save is blocked, not whether the mapping would reach the
+CRM.
+
+### A sending service
+
+The host app doesn't have to talk to HubSpot itself — the plugin exposes the
+upsert, with everything above applied on the way out:
+
+```ts
+const result = await strapi.plugin("hubspot").service("submit").upsert({
+  object: "contact",
+  idProperty: "email", // find-or-create key
+  properties: {
+    email: "jane@acme.com",
+    firstname: "Jane",
+    hs_role: "dev;designer", // multi-select values use HubSpot's `;` separator
+  },
+});
+// { ok: true, id: "…" }
+// { ok: false, problems: [{ code: "unknown", … }] }  — refused before sending
+// { ok: false, queued: true, error: "…" }            — parked for replay
+```
+
+The payload is validated against the portal schema **before** it is sent —
+the same checks as on save, values coerced to strings, empty ones dropped.
+Then:
+
+- a **permanent refusal** (4xx) comes back as `{ ok: false, error }` with
+  HubSpot's message — retrying can't fix a wrong payload, so nothing is queued;
+- a **transient failure** (429, 5xx, network) is retried twice with backoff,
+  then parked in **Content Manager → HubSpot failed submissions** and reported
+  as `{ ok: false, queued: true }`.
+
+`service("submit").retryFailures()` replays the queue, oldest first — from a
+cron in the host app, or the **Replay now** button in Settings → HubSpot. A
+replay that succeeds removes the row; one that keeps failing stays, with its
+error and attempt count, until it works or an admin deletes it.
+
+Sending needs write scopes on the token: `crm.objects.contacts.write` (and
+its equivalent per object you send to).
+
 ### A settings screen
 
 **Settings → HubSpot** holds the private app token. It is stored server-side and
@@ -98,6 +190,11 @@ never returned to the browser: the UI only receives whether a key exists, where
 it comes from, and its last four characters. A "Test connection" button
 round-trips to HubSpot and reports how many properties it can read.
 
+Access is gated by a dedicated RBAC permission — **Settings →
+Roles → Plugins → Hubspot**. A role without it neither sees the settings link
+nor can call the settings routes; reading properties stays open to every
+authenticated admin, since the picker needs it in the Content Manager.
+
 > **On storage:** the key is kept in Strapi's core store, which is **not
 > encrypted at rest** — it is readable by anyone with database access. It never
 > reaches the browser, but treat it like any other secret in your database. Use
@@ -132,6 +229,8 @@ export default ({ env }) => ({
           objectField: "hsObject",     // holds "contact" | "company"
           propertyField: "hsProperty", // holds the property name
           optionsField: "options",     // optional — the field's choices
+          strict: true,                // optional — false lets `unknown`
+                                       // properties through with a warning
         },
       ],
     },
@@ -201,7 +300,7 @@ This one never blocks work:
 |---|---|
 | No API key configured | The field falls back to a plain text input, with a note explaining why |
 | HubSpot unreachable | Saving proceeds; validation is skipped and a warning is logged |
-| Property staged in HubSpot but not created yet | The picker accepts a typed value (`creatable`) |
+| Property staged in HubSpot but not created yet | The picker accepts a typed value (`creatable`); set `strict: false` on the validate target so the save passes too |
 | An object's scope is missing | That object is skipped; the others still work |
 | Portal id unreadable | Deep links are omitted; everything else is unaffected |
 | Plugin uninstalled | Values remain as strings — nothing to undo |
@@ -212,15 +311,35 @@ key drops the cache immediately.
 
 ## Admin API
 
-All routes require an authenticated admin.
+All routes require an authenticated admin; the settings routes additionally
+require the `plugin::hubspot.settings` RBAC permission.
 
 | Method | Path | Purpose |
 |---|---|---|
 | `GET` | `/hubspot/properties` | Writable properties, readable objects, unreachable ones and the portal id. `?refresh=1` bypasses the cache |
+| `GET` | `/hubspot/audit` | Scans every entry of the validated content types and returns the invalid mappings, per entry |
+| `GET` | `/hubspot/failures` | Number of parked submissions |
+| `POST` | `/hubspot/failures/retry` | Replays the parked submissions and reports the outcome |
 | `GET` | `/hubspot/settings` | Whether a key exists, its source and hint — never the key |
 | `PUT` | `/hubspot/settings` | Save a key (`{ apiKey }`) |
 | `DELETE` | `/hubspot/settings` | Remove the stored key |
 
+## i18n
+
+The admin UI ships in English and French, keyed on the Strapi admin locale.
+Server-side error messages stay in English; the structured codes in the
+error's `details` are the localization hook for host apps.
+
+## Tests
+
+```bash
+npm test
+```
+
+Vitest over the server logic: mapping checks, deep collection through dynamic
+zones and repeatables, schema loading (cache, concurrent de-duplication,
+missing scopes) and the strict/non-strict save middleware.
+
 ## Compatibility
 
 Strapi **v5**. Node **>= 18**.

package/dist/_chunks/HubspotObjectInput-DiYaEyE7.mjs

@@ -0,0 +1,73 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { u as useIntl, o as objectLabel } from "./objectLabels-DKr0yCaU.mjs";
+import { Field, Flex, Loader, SingleSelect, SingleSelectOption } from "@strapi/design-system";
+import { useFetchClient } from "@strapi/strapi/admin";
+import { P as PLUGIN_ID, g as getTranslation } from "./index-ymm9UsG8.mjs";
+const HubspotObjectInput = React.forwardRef(
+  ({ name, value, onChange, disabled, error, required, label, hint, labelAction }, ref) => {
+    const intl = useIntl();
+    const { formatMessage } = intl;
+    const { get } = useFetchClient();
+    const [schema, setSchema] = React.useState(null);
+    React.useEffect(() => {
+      let cancelled = false;
+      get(`/${PLUGIN_ID}/properties`).then(({ data }) => {
+        if (!cancelled) setSchema(data);
+      }).catch(() => {
+        if (!cancelled) setSchema({ configured: false, objects: [], unavailable: [] });
+      });
+      return () => {
+        cancelled = true;
+      };
+    }, [get]);
+    const emit = (next) => onChange({ target: { name, value: String(next ?? ""), type: "string" } });
+    const known = [
+      ...schema?.objects ?? [],
+      ...(schema?.unavailable ?? []).map((u) => u.object)
+    ];
+    const options = value && !known.includes(value) ? [value, ...known] : known;
+    return /* @__PURE__ */ jsxs(Field.Root, { name, error, hint, required, children: [
+      /* @__PURE__ */ jsx(Field.Label, { action: labelAction, children: label }),
+      !schema ? /* @__PURE__ */ jsx(Flex, { paddingTop: 2, paddingBottom: 2, children: /* @__PURE__ */ jsx(Loader, { small: true, children: formatMessage({
+        id: getTranslation("object.loading"),
+        defaultMessage: "Loading HubSpot objects…"
+      }) }) }) : schema.configured ? /* @__PURE__ */ jsx(
+        SingleSelect,
+        {
+          ref,
+          value: value || "",
+          onChange: emit,
+          onClear: () => emit(""),
+          disabled,
+          placeholder: formatMessage({
+            id: getTranslation("object.placeholder"),
+            defaultMessage: "Choose an object…"
+          }),
+          children: options.map((object) => /* @__PURE__ */ jsx(SingleSelectOption, { value: object, children: schema.unavailable.some((u) => u.object === object) ? formatMessage(
+            {
+              id: getTranslation("object.no-scope"),
+              defaultMessage: "{object} — missing scope on the token"
+            },
+            { object: objectLabel(intl, object) }
+          ) : objectLabel(intl, object) }, object))
+        }
+      ) : /* @__PURE__ */ jsx(
+        Field.Input,
+        {
+          ref,
+          value: value || "",
+          onChange: (e) => emit(e.target.value),
+          disabled,
+          placeholder: "contact"
+        }
+      ),
+      /* @__PURE__ */ jsx(Field.Hint, {}),
+      /* @__PURE__ */ jsx(Field.Error, {})
+    ] });
+  }
+);
+HubspotObjectInput.displayName = "HubspotObjectInput";
+export {
+  HubspotObjectInput as default
+};

package/dist/_chunks/HubspotObjectInput-Dqgz6Epv.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const React = require("react");
+const objectLabels = require("./objectLabels-CORLL0o7.js");
+const designSystem = require("@strapi/design-system");
+const admin = require("@strapi/strapi/admin");
+const index = require("./index-CDpmcrIu.js");
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });
+  if (e) {
+    for (const k in e) {
+      if (k !== "default") {
+        const d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: () => e[k]
+        });
+      }
+    }
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+const React__namespace = /* @__PURE__ */ _interopNamespace(React);
+const HubspotObjectInput = React__namespace.forwardRef(
+  ({ name, value, onChange, disabled, error, required, label, hint, labelAction }, ref) => {
+    const intl = objectLabels.useIntl();
+    const { formatMessage } = intl;
+    const { get } = admin.useFetchClient();
+    const [schema, setSchema] = React__namespace.useState(null);
+    React__namespace.useEffect(() => {
+      let cancelled = false;
+      get(`/${index.PLUGIN_ID}/properties`).then(({ data }) => {
+        if (!cancelled) setSchema(data);
+      }).catch(() => {
+        if (!cancelled) setSchema({ configured: false, objects: [], unavailable: [] });
+      });
+      return () => {
+        cancelled = true;
+      };
+    }, [get]);
+    const emit = (next) => onChange({ target: { name, value: String(next ?? ""), type: "string" } });
+    const known = [
+      ...schema?.objects ?? [],
+      ...(schema?.unavailable ?? []).map((u) => u.object)
+    ];
+    const options = value && !known.includes(value) ? [value, ...known] : known;
+    return /* @__PURE__ */ jsxRuntime.jsxs(designSystem.Field.Root, { name, error, hint, required, children: [
+      /* @__PURE__ */ jsxRuntime.jsx(designSystem.Field.Label, { action: labelAction, children: label }),
+      !schema ? /* @__PURE__ */ jsxRuntime.jsx(designSystem.Flex, { paddingTop: 2, paddingBottom: 2, children: /* @__PURE__ */ jsxRuntime.jsx(designSystem.Loader, { small: true, children: formatMessage({
+        id: index.getTranslation("object.loading"),
+        defaultMessage: "Loading HubSpot objects…"
+      }) }) }) : schema.configured ? /* @__PURE__ */ jsxRuntime.jsx(
+        designSystem.SingleSelect,
+        {
+          ref,
+          value: value || "",
+          onChange: emit,
+          onClear: () => emit(""),
+          disabled,
+          placeholder: formatMessage({
+            id: index.getTranslation("object.placeholder"),
+            defaultMessage: "Choose an object…"
+          }),
+          children: options.map((object) => /* @__PURE__ */ jsxRuntime.jsx(designSystem.SingleSelectOption, { value: object, children: schema.unavailable.some((u) => u.object === object) ? formatMessage(
+            {
+              id: index.getTranslation("object.no-scope"),
+              defaultMessage: "{object} — missing scope on the token"
+            },
+            { object: objectLabels.objectLabel(intl, object) }
+          ) : objectLabels.objectLabel(intl, object) }, object))
+        }
+      ) : /* @__PURE__ */ jsxRuntime.jsx(
+        designSystem.Field.Input,
+        {
+          ref,
+          value: value || "",
+          onChange: (e) => emit(e.target.value),
+          disabled,
+          placeholder: "contact"
+        }
+      ),
+      /* @__PURE__ */ jsxRuntime.jsx(designSystem.Field.Hint, {}),
+      /* @__PURE__ */ jsxRuntime.jsx(designSystem.Field.Error, {})
+    ] });
+  }
+);
+HubspotObjectInput.displayName = "HubspotObjectInput";
+exports.default = HubspotObjectInput;

package/dist/_chunks/HubspotPropertyInput-BUbQk1CX.mjs

@@ -0,0 +1,174 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { u as useIntl, o as objectLabel } from "./objectLabels-DKr0yCaU.mjs";
+import { Field, Flex, Loader, Combobox, ComboboxOption, Button, Typography, Link } from "@strapi/design-system";
+import { useFetchClient, useField } from "@strapi/strapi/admin";
+import { P as PLUGIN_ID, g as getTranslation } from "./index-ymm9UsG8.mjs";
+const oneLine = {
+  display: "block",
+  whiteSpace: "nowrap",
+  overflow: "hidden",
+  textOverflow: "ellipsis"
+};
+const HubspotPropertyInput = React.forwardRef(
+  ({ name, value, onChange, attribute, disabled, error, required, label, hint, labelAction }, ref) => {
+    const intl = useIntl();
+    const { formatMessage } = intl;
+    const { get } = useFetchClient();
+    const [schema, setSchema] = React.useState(null);
+    const [loadError, setLoadError] = React.useState("");
+    const objectFieldName = attribute?.options?.objectField || "hsObject";
+    const siblingPath = React.useMemo(
+      () => name.replace(/[^.]+$/, objectFieldName),
+      [name, objectFieldName]
+    );
+    const siblingField = useField(siblingPath);
+    const selectedObject = siblingField?.value;
+    const optionsFieldName = attribute?.options?.optionsField || "options";
+    const optionsPath = React.useMemo(
+      () => name.replace(/[^.]+$/, optionsFieldName),
+      [name, optionsFieldName]
+    );
+    const optionsField = useField(optionsPath);
+    const [imported, setImported] = React.useState(false);
+    React.useEffect(() => {
+      let cancelled = false;
+      get(`/${PLUGIN_ID}/properties`).then(({ data }) => {
+        if (!cancelled) setSchema(data);
+      }).catch((err) => {
+        if (cancelled) return;
+        setSchema({ configured: false, properties: [], objects: [], unavailable: [] });
+        setLoadError(
+          err?.response?.data?.error?.message ?? formatMessage({
+            id: getTranslation("picker.load-error"),
+            defaultMessage: "HubSpot properties unavailable"
+          })
+        );
+      });
+      return () => {
+        cancelled = true;
+      };
+    }, [get]);
+    const emit = (next) => onChange({ target: { name, value: next ?? "", type: "string" } });
+    const options = React.useMemo(() => {
+      const all = schema?.properties ?? [];
+      const scoped = selectedObject ? all.filter((p) => p.object === selectedObject) : all;
+      const sorted = selectedObject ? [...scoped].sort(
+        (a, b) => (a.group ?? "").localeCompare(b.group ?? "") || a.label.localeCompare(b.label)
+      ) : scoped;
+      const shown = sorted.map((p) => ({
+        value: p.name,
+        label: selectedObject ? `${p.group ? `${p.group} · ` : ""}${p.label} (${p.name})` : `${objectLabel(intl, p.object)} · ${p.label} (${p.name})`
+      }));
+      if (value && !scoped.some((p) => p.name === value)) {
+        const elsewhere = all.find((p) => p.name === value);
+        shown.unshift({
+          value,
+          label: elsewhere ? formatMessage(
+            { id: getTranslation("picker.belongs-to"), defaultMessage: "{property} — belongs to {object}" },
+            { property: value, object: objectLabel(intl, elsewhere.object) }
+          ) : formatMessage(
+            { id: getTranslation("picker.unknown"), defaultMessage: "{property} — unknown to the portal" },
+            { property: value }
+          )
+        });
+      }
+      return shown;
+    }, [schema, selectedObject, value, intl, formatMessage]);
+    const describe = () => {
+      if (loadError) return loadError;
+      if (schema && !schema.configured) {
+        return formatMessage({
+          id: getTranslation("picker.not-configured"),
+          defaultMessage: "No HubSpot API key — free text. Set it in Settings → HubSpot."
+        });
+      }
+      if (selectedObject && schema?.unavailable.some((u) => u.object === selectedObject)) {
+        return formatMessage(
+          {
+            id: getTranslation("picker.object-unavailable"),
+            defaultMessage: "Properties of “{object}” unreadable — missing scope on the token."
+          },
+          { object: objectLabel(intl, selectedObject) }
+        );
+      }
+      return hint;
+    };
+    const crmLink = schema?.portalId && value && schema.properties.some((p) => p.name === value) ? `https://${schema.uiDomain || "app.hubspot.com"}/property-settings/${schema.portalId}/properties?search=${encodeURIComponent(value)}` : null;
+    const selectedProperty = value && schema ? schema.properties.find(
+      (p) => p.name === value && (!selectedObject || p.object === selectedObject)
+    ) : void 0;
+    const importable = selectedProperty?.type === "enumeration" && (selectedProperty.options?.length ?? 0) > 0;
+    React.useEffect(() => setImported(false), [value]);
+    const importOptions = () => {
+      if (!selectedProperty || !optionsField) return;
+      const rows = selectedProperty.options.map((o, i) => ({
+        __temp_key__: `a${i}`,
+        value: o.value,
+        label: o.label ?? o.value
+      }));
+      optionsField.onChange({
+        target: { name: optionsPath, value: rows, type: "json" }
+      });
+      setImported(true);
+    };
+    return /* @__PURE__ */ jsxs(Field.Root, { name, error, hint: describe(), required, children: [
+      /* @__PURE__ */ jsx(Field.Label, { action: labelAction, children: label }),
+      !schema ? /* @__PURE__ */ jsx(Flex, { paddingTop: 2, paddingBottom: 2, children: /* @__PURE__ */ jsx(Loader, { small: true, children: formatMessage({
+        id: getTranslation("picker.loading"),
+        defaultMessage: "Loading HubSpot properties…"
+      }) }) }) : schema.configured ? /* @__PURE__ */ jsx(
+        Combobox,
+        {
+          ref,
+          value: value || "",
+          onChange: emit,
+          onClear: () => emit(""),
+          disabled,
+          placeholder: formatMessage({
+            id: getTranslation("picker.placeholder"),
+            defaultMessage: "Search a property…"
+          }),
+          creatable: true,
+          onCreateOption: emit,
+          children: options.map((o) => /* @__PURE__ */ jsx(ComboboxOption, { value: o.value, textValue: o.label, children: /* @__PURE__ */ jsx("span", { title: o.label, style: oneLine, children: o.label }) }, o.value))
+        }
+      ) : /* @__PURE__ */ jsx(
+        Field.Input,
+        {
+          ref,
+          value: value || "",
+          onChange: (e) => emit(e.target.value),
+          disabled,
+          placeholder: formatMessage({
+            id: getTranslation("picker.free-placeholder"),
+            defaultMessage: "e.g. hs_role, numberofemployees"
+          })
+        }
+      ),
+      crmLink || importable ? /* @__PURE__ */ jsxs(Flex, { paddingTop: 1, gap: 3, alignItems: "center", wrap: "wrap", children: [
+        importable ? /* @__PURE__ */ jsx(Button, { variant: "tertiary", size: "S", onClick: importOptions, disabled, children: formatMessage(
+          {
+            id: getTranslation("picker.import"),
+            defaultMessage: "Import the {count} options from HubSpot"
+          },
+          { count: selectedProperty?.options.length ?? 0 }
+        ) }) : null,
+        imported ? /* @__PURE__ */ jsx(Typography, { variant: "pi", textColor: "success600", children: formatMessage({
+          id: getTranslation("picker.imported"),
+          defaultMessage: "Options imported — save to keep them."
+        }) }) : null,
+        crmLink ? /* @__PURE__ */ jsx(Link, { href: crmLink, isExternal: true, children: formatMessage({
+          id: getTranslation("picker.view"),
+          defaultMessage: "View in HubSpot"
+        }) }) : null
+      ] }) : null,
+      /* @__PURE__ */ jsx(Field.Hint, {}),
+      /* @__PURE__ */ jsx(Field.Error, {})
+    ] });
+  }
+);
+HubspotPropertyInput.displayName = "HubspotPropertyInput";
+export {
+  HubspotPropertyInput as default
+};