strapi-plugin-hubspot 0.3.0 → 0.4.0

package/dist/server/index.mjs

@@ -1,5 +1,5 @@
 import { errors } from "@strapi/utils";
-const HS_BASE = "https://api.hubapi.com";
+const HS_BASE$1 = "https://api.hubapi.com";
 const TTL_MS = 10 * 60 * 1e3;
 const STANDARD_OBJECTS = [
   { name: "contact", path: "contacts" },
@@ -13,7 +13,7 @@ const STANDARD_OBJECTS = [
 let cache = null;
 let inFlight = null;
 async function hsGet(apiKey, path) {
-  const res = await fetch(`${HS_BASE}${path}`, {
+  const res = await fetch(`${HS_BASE$1}${path}`, {
     headers: { Authorization: `Bearer ${apiKey}` }
   });
   if (!res.ok) {
@@ -24,18 +24,29 @@ async function hsGet(apiKey, path) {
   }
   return await res.json();
 }
+async function fetchGroups(apiKey, path) {
+  try {
+    const res = await hsGet(
+      apiKey,
+      `/crm/v3/properties/${path}/groups`
+    );
+    return Object.fromEntries((res.results ?? []).map((g) => [g.name, g.label || g.name]));
+  } catch {
+    return {};
+  }
+}
 async function fetchObject(apiKey, object) {
-  const res = await hsGet(
-    apiKey,
-    `/crm/v3/properties/${object.path}`
-  );
+  const [res, groups] = await Promise.all([
+    hsGet(apiKey, `/crm/v3/properties/${object.path}`),
+    fetchGroups(apiKey, object.path)
+  ]);
   return (res.results ?? []).filter((p) => !p.modificationMetadata?.readOnlyValue).map((p) => ({
     name: p.name,
     label: p.label || p.name,
     object: object.name,
     type: p.type,
-    options: (p.options ?? []).map((o) => o.value),
-    group: p.groupName
+    options: (p.options ?? []).map((o) => ({ value: o.value, label: o.label })),
+    group: p.groupName ? groups[p.groupName] ?? p.groupName : void 0
   }));
 }
 async function fetchAccount(apiKey) {
@@ -110,7 +121,8 @@ function checkMapping(properties, mapping) {
   }
   if (trimmed !== property) return { code: "whitespace", property, object };
   if (match.type === "enumeration" && match.options.length && mapping.values?.length) {
-    const stray = mapping.values.filter((v) => v && !match.options.includes(v));
+    const allowed = match.options.map((o) => o.value);
+    const stray = mapping.values.filter((v) => v && !allowed.includes(v));
     if (stray.length) {
       return { code: "bad-option", property: trimmed, object, values: stray };
     }
@@ -171,6 +183,337 @@ async function publicSettings(strapi) {
     hint: apiKey ? `…${apiKey.slice(-4)}` : ""
   };
 }
+function collectMappings(node, target, found = []) {
+  if (Array.isArray(node)) {
+    for (const item of node) collectMappings(item, target, found);
+    return found;
+  }
+  if (!node || typeof node !== "object") return found;
+  const obj = node;
+  const property = obj[target.propertyField];
+  if (typeof property === "string" && property.trim()) {
+    const object = obj[target.objectField];
+    const rawOptions = obj[target.optionsField || "options"];
+    const values = Array.isArray(rawOptions) ? rawOptions.map((o) => {
+      const opt = o ?? {};
+      const v = typeof opt.value === "string" && opt.value.trim() ? opt.value : opt.label;
+      return typeof v === "string" ? v.trim() : "";
+    }).filter(Boolean) : void 0;
+    found.push({
+      object: typeof object === "string" && object ? object : "contact",
+      property,
+      values
+    });
+  }
+  for (const value of Object.values(obj)) collectMappings(value, target, found);
+  return found;
+}
+function makeValidationMiddleware(strapi, target) {
+  return async (context, next) => {
+    const isWrite = ["create", "update"].includes(context.action);
+    if (!isWrite || context.uid !== target.uid) return next();
+    const mappings = collectMappings(
+      context.params?.data,
+      target
+    );
+    if (!mappings.length) return next();
+    const { apiKey } = await resolveApiKey(strapi);
+    if (!apiKey) return next();
+    let schema;
+    try {
+      schema = await loadSchema(
+        strapi,
+        apiKey,
+        resolveObjects(strapi.plugin("hubspot").config("objects", []))
+      );
+    } catch {
+      strapi.log.warn("[hubspot] schema unavailable — validation skipped");
+      return next();
+    }
+    const problems = mappings.map((m) => checkMapping(schema.properties, m)).filter((p) => Boolean(p));
+    const blocking = target.strict === false ? problems.filter((p) => p.code !== "unknown") : problems;
+    const soft = problems.filter((p) => !blocking.includes(p));
+    if (soft.length) {
+      const sentences = [...new Set(soft.map(describeProblem))];
+      strapi.log.warn(
+        `[hubspot] ${target.uid}: ${sentences.join("; ")} — allowed (strict: false)`
+      );
+    }
+    if (blocking.length) {
+      const sentences = [...new Set(blocking.map(describeProblem))];
+      throw new errors.ValidationError(
+        `Invalid HubSpot mapping — ${sentences.join("; ")}`,
+        { problems: blocking }
+      );
+    }
+    return next();
+  };
+}
+function buildPopulate(components, schema, depth = 0) {
+  if (depth > 8) return {};
+  const populate = {};
+  for (const [key, attr] of Object.entries(schema.attributes ?? {})) {
+    if (attr.type === "component" && attr.component) {
+      const child = components[attr.component];
+      const nested = child ? buildPopulate(components, child, depth + 1) : {};
+      populate[key] = { populate: Object.keys(nested).length ? nested : "*" };
+    } else if (attr.type === "dynamiczone" && attr.components?.length) {
+      const on = {};
+      for (const uid of attr.components) {
+        const child = components[uid];
+        const nested = child ? buildPopulate(components, child, depth + 1) : {};
+        on[uid] = { populate: Object.keys(nested).length ? nested : "*" };
+      }
+      populate[key] = { on };
+    }
+  }
+  return populate;
+}
+function entryLabel(entry) {
+  for (const key of ["title", "name", "label", "heading", "slug"]) {
+    const value = entry[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return String(entry.documentId ?? entry.id ?? "?");
+}
+async function fetchEntries(strapi, uid, schema, populate) {
+  const params = {};
+  if (Object.keys(populate).length) params.populate = populate;
+  if (schema.options?.draftAndPublish) params.status = "draft";
+  let locales = [void 0];
+  if (schema.pluginOptions?.i18n?.localized) {
+    try {
+      const known = await strapi.plugin("i18n").service("locales").find();
+      if (known.length) locales = known.map((l) => l.code);
+    } catch {
+    }
+  }
+  const out = [];
+  for (const locale of locales) {
+    const docs = await strapi.documents(uid).findMany({
+      ...params,
+      ...locale ? { locale } : {}
+    });
+    for (const doc of docs ?? []) out.push(locale ? { ...doc, __auditLocale: locale } : doc);
+  }
+  return out;
+}
+async function runAudit(strapi, targets, schema) {
+  const reports = [];
+  for (const target of targets) {
+    const contentType = strapi.contentType(target.uid);
+    if (!contentType) {
+      reports.push({
+        uid: target.uid,
+        entries: 0,
+        mappings: 0,
+        invalid: [],
+        error: `unknown content type "${target.uid}"`
+      });
+      continue;
+    }
+    const populate = buildPopulate(
+      strapi.components,
+      contentType
+    );
+    let entries;
+    try {
+      entries = await fetchEntries(strapi, target.uid, contentType, populate);
+    } catch (err) {
+      reports.push({
+        uid: target.uid,
+        entries: 0,
+        mappings: 0,
+        invalid: [],
+        error: err.message
+      });
+      continue;
+    }
+    const report = {
+      uid: target.uid,
+      entries: entries.length,
+      mappings: 0,
+      invalid: []
+    };
+    for (const entry of entries) {
+      const mappings = collectMappings(entry, target);
+      report.mappings += mappings.length;
+      const problems = mappings.map((m) => checkMapping(schema.properties, m)).filter((p) => Boolean(p));
+      if (problems.length) {
+        report.invalid.push({
+          documentId: String(entry.documentId ?? entry.id ?? "?"),
+          locale: entry.__auditLocale ?? void 0,
+          label: entryLabel(entry),
+          problems
+        });
+      }
+    }
+    reports.push(report);
+  }
+  return reports;
+}
+const contentTypes = {
+  failure: {
+    schema: {
+      kind: "collectionType",
+      collectionName: "hubspot_failures",
+      info: {
+        singularName: "failure",
+        pluralName: "failures",
+        displayName: "HubSpot failed submissions",
+        description: "Submissions HubSpot couldn't take, waiting to be replayed"
+      },
+      options: { draftAndPublish: false },
+      pluginOptions: {
+        "content-manager": { visible: true },
+        "content-type-builder": { visible: false }
+      },
+      attributes: {
+        object: { type: "string", required: true },
+        idProperty: { type: "string", required: true },
+        properties: { type: "json", required: true },
+        error: { type: "text" },
+        attempts: { type: "integer", default: 1 }
+      }
+    }
+  }
+};
+const HS_BASE = "https://api.hubapi.com";
+const FAILURE_UID = "plugin::hubspot.failure";
+const RETRY_DELAYS_MS = [500, 2e3];
+const sleepFor = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function coerceProperties(properties) {
+  const out = {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (value === null || value === void 0 || value === "") continue;
+    out[key] = String(value);
+  }
+  return out;
+}
+class HsError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
+const isTransient = (err) => !(err instanceof HsError) || err.status === 429 || err.status >= 500;
+function createSubmitService(strapi, { sleep = sleepFor } = {}) {
+  const objectPath = (object) => resolveObjects(strapi.plugin("hubspot").config("objects", [])).find(
+    (o) => o.name === object
+  )?.path ?? object;
+  async function sendOnce(apiKey, input, properties) {
+    const res = await fetch(`${HS_BASE}/crm/v3/objects/${objectPath(input.object)}/batch/upsert`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        inputs: [{ idProperty: input.idProperty, id: properties[input.idProperty], properties }]
+      })
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) throw new HsError(body.message || `HubSpot ${res.status}`, res.status);
+    return body.results?.[0]?.id ?? "";
+  }
+  async function sendWithRetries(apiKey, input, properties) {
+    let lastError;
+    for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt += 1) {
+      if (attempt > 0) await sleep(RETRY_DELAYS_MS[attempt - 1]);
+      try {
+        return await sendOnce(apiKey, input, properties);
+      } catch (err) {
+        lastError = err;
+        if (!isTransient(err)) throw err;
+      }
+    }
+    throw lastError;
+  }
+  async function validateAgainstSchema(apiKey, input, properties) {
+    let schema;
+    try {
+      schema = await loadSchema(
+        strapi,
+        apiKey,
+        resolveObjects(strapi.plugin("hubspot").config("objects", []))
+      );
+    } catch {
+      return null;
+    }
+    const problems = [];
+    for (const [name, value] of Object.entries(properties)) {
+      const problem = checkMapping(schema.properties, {
+        object: input.object,
+        property: name,
+        values: value.split(";").map((v) => v.trim()).filter(Boolean)
+      });
+      if (problem) problems.push(problem);
+    }
+    return problems;
+  }
+  async function upsert(input, { queueOnFailure = true } = {}) {
+    const { apiKey } = await resolveApiKey(strapi);
+    if (!apiKey) return { ok: false, error: "No HubSpot API key configured" };
+    const properties = coerceProperties(input.properties);
+    if (!properties[input.idProperty]) {
+      return { ok: false, error: `Missing value for idProperty "${input.idProperty}"` };
+    }
+    const problems = await validateAgainstSchema(apiKey, input, properties);
+    if (problems?.length) return { ok: false, problems };
+    try {
+      const id = await sendWithRetries(apiKey, input, properties);
+      return { ok: true, id };
+    } catch (err) {
+      const message = err.message;
+      if (!isTransient(err) || !queueOnFailure) {
+        strapi.log.error(`[hubspot] upsert refused — ${message}`);
+        return { ok: false, error: message };
+      }
+      strapi.log.warn(`[hubspot] upsert failed, queued for retry — ${message}`);
+      try {
+        await strapi.documents(FAILURE_UID).create({
+          data: {
+            object: input.object,
+            idProperty: input.idProperty,
+            properties: input.properties,
+            error: message,
+            attempts: 1
+          }
+        });
+        return { ok: false, queued: true, error: message };
+      } catch (storeErr) {
+        strapi.log.error(`[hubspot] could not queue the failure — ${storeErr.message}`);
+        return { ok: false, queued: false, error: message };
+      }
+    }
+  }
+  async function retryFailures({ limit = 50 } = {}) {
+    const rows = await strapi.documents(FAILURE_UID).findMany({
+      limit,
+      sort: "createdAt:asc"
+    });
+    let succeeded = 0;
+    for (const row of rows) {
+      const result = await upsert(
+        { object: row.object, idProperty: row.idProperty, properties: row.properties ?? {} },
+        { queueOnFailure: false }
+        // Already queued — don't duplicate the row.
+      );
+      if (result.ok) {
+        await strapi.documents(FAILURE_UID).delete({ documentId: row.documentId });
+        succeeded += 1;
+      } else {
+        await strapi.documents(FAILURE_UID).update({
+          documentId: row.documentId,
+          data: {
+            attempts: (row.attempts ?? 1) + 1,
+            error: result.error ?? (result.problems ? `invalid mapping: ${JSON.stringify(result.problems)}` : "unknown")
+          }
+        });
+      }
+    }
+    return { retried: rows.length, succeeded, failed: rows.length - succeeded };
+  }
+  return { upsert, retryFailures };
+}
+const SETTINGS_ACTION = "plugin::hubspot.settings";
 const config = {
   default: {
     apiKey: "",
@@ -207,6 +550,37 @@ const controllers = {
       }
     }
   }),
+  audit: ({ strapi }) => ({
+    async run(ctx) {
+      const { apiKey } = await resolveApiKey(strapi);
+      if (!apiKey) {
+        ctx.body = { configured: false, targets: [] };
+        return;
+      }
+      const targets = strapi.plugin("hubspot").config("validate", []);
+      try {
+        const schema = await loadSchema(
+          strapi,
+          apiKey,
+          resolveObjects(strapi.plugin("hubspot").config("objects", [])),
+          { force: true }
+        );
+        ctx.body = { configured: true, targets: await runAudit(strapi, targets, schema) };
+      } catch (err) {
+        strapi.log.error(`[hubspot] audit failed — ${err.message}`);
+        ctx.throw(502, "Cannot reach HubSpot — check the API key.");
+      }
+    }
+  }),
+  failures: ({ strapi }) => ({
+    async list(ctx) {
+      const total = await strapi.documents(FAILURE_UID).count({});
+      ctx.body = { total };
+    },
+    async retry(ctx) {
+      ctx.body = await strapi.plugin("hubspot").service("submit").retryFailures();
+    }
+  }),
   settings: ({ strapi }) => ({
     async get(ctx) {
       ctx.body = await publicSettings(strapi);
@@ -222,91 +596,65 @@ const controllers = {
     }
   })
 };
-const adminRoute = (method, path, handler) => ({
+const adminRoute = (method, path, handler, actions) => ({
   method,
   path,
   handler,
-  config: { policies: ["admin::isAuthenticatedAdmin"] }
+  config: {
+    policies: [
+      "admin::isAuthenticatedAdmin",
+      // The token is a portal-wide secret; reading properties is not. Only the
+      // settings routes carry the extra permission.
+      ...actions ? [{ name: "admin::hasPermissions", config: { actions } }] : []
+    ]
+  }
 });
 const routes = {
   admin: {
     type: "admin",
     routes: [
       adminRoute("GET", "/properties", "properties.list"),
-      adminRoute("GET", "/settings", "settings.get"),
-      adminRoute("PUT", "/settings", "settings.update"),
-      adminRoute("DELETE", "/settings", "settings.reset")
+      adminRoute("GET", "/audit", "audit.run", [SETTINGS_ACTION]),
+      adminRoute("GET", "/failures", "failures.list", [SETTINGS_ACTION]),
+      adminRoute("POST", "/failures/retry", "failures.retry", [SETTINGS_ACTION]),
+      adminRoute("GET", "/settings", "settings.get", [SETTINGS_ACTION]),
+      adminRoute("PUT", "/settings", "settings.update", [SETTINGS_ACTION]),
+      adminRoute("DELETE", "/settings", "settings.reset", [SETTINGS_ACTION])
     ]
   }
 };
-function collectMappings(node, target, found = []) {
-  if (Array.isArray(node)) {
-    for (const item of node) collectMappings(item, target, found);
-    return found;
-  }
-  if (!node || typeof node !== "object") return found;
-  const obj = node;
-  const property = obj[target.propertyField];
-  if (typeof property === "string" && property.trim()) {
-    const object = obj[target.objectField];
-    const rawOptions = obj[target.optionsField || "options"];
-    const values = Array.isArray(rawOptions) ? rawOptions.map((o) => {
-      const opt = o ?? {};
-      const v = typeof opt.value === "string" && opt.value.trim() ? opt.value : opt.label;
-      return typeof v === "string" ? v.trim() : "";
-    }).filter(Boolean) : void 0;
-    found.push({
-      object: typeof object === "string" && object ? object : "contact",
-      property,
-      values
-    });
-  }
-  for (const value of Object.values(obj)) collectMappings(value, target, found);
-  return found;
-}
 const index = {
   config,
+  contentTypes,
   controllers,
   routes,
+  services: {
+    submit: ({ strapi }) => createSubmitService(strapi)
+  },
   register({ strapi }) {
     strapi.customFields.register({
       name: "property",
       plugin: "hubspot",
       type: "string"
     });
+    strapi.customFields.register({
+      name: "object",
+      plugin: "hubspot",
+      type: "string"
+    });
   },
-  bootstrap({ strapi }) {
+  async bootstrap({ strapi }) {
+    await strapi.service("admin::permission").actionProvider.registerMany([
+      {
+        section: "plugins",
+        displayName: "Access the HubSpot settings",
+        uid: "settings",
+        pluginName: "hubspot"
+      }
+    ]);
     const targets = strapi.plugin("hubspot").config("validate", []);
-    if (!targets.length) return;
     for (const target of targets) {
-      strapi.documents.use(async (context, next) => {
-        const isWrite = ["create", "update"].includes(context.action);
-        if (!isWrite || context.uid !== target.uid) return next();
-        const mappings = collectMappings(context.params?.data, target);
-        if (!mappings.length) return next();
-        const { apiKey } = await resolveApiKey(strapi);
-        if (!apiKey) return next();
-        let schema;
-        try {
-          schema = await loadSchema(
-            strapi,
-            apiKey,
-            resolveObjects(strapi.plugin("hubspot").config("objects", []))
-          );
-        } catch {
-          strapi.log.warn("[hubspot] schema unavailable — validation skipped");
-          return next();
-        }
-        const problems = mappings.map((m) => checkMapping(schema.properties, m)).filter((p) => Boolean(p));
-        if (problems.length) {
-          const sentences = [...new Set(problems.map(describeProblem))];
-          throw new errors.ValidationError(
-            `Invalid HubSpot mapping — ${sentences.join("; ")}`,
-            { problems }
-          );
-        }
-        return next();
-      });
+      strapi.documents.use(makeValidationMiddleware(strapi, target));
     }
   }
 };

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,60 @@
+import type { Core } from "@strapi/strapi";
+import { type Problem, type Schema } from "./properties";
+import { type ValidateTarget } from "./validation";
+/**
+ * Full-content audit of HubSpot mappings.
+ *
+ * Save-time validation only protects entries as they are written: a property
+ * deleted in HubSpot afterwards leaves invalid mappings dormant in content
+ * that nobody re-saves. The audit walks every entry of every validated content
+ * type and reports the mappings the portal would reject today.
+ *
+ * Problems are returned as structured codes — the admin UI renders and
+ * translates them, symmetrical with save-time validation's `details`.
+ */
+interface AttributeSchema {
+    type: string;
+    component?: string;
+    components?: string[];
+}
+interface EntitySchema {
+    attributes: Record<string, AttributeSchema>;
+    options?: {
+        draftAndPublish?: boolean;
+    };
+    pluginOptions?: {
+        i18n?: {
+            localized?: boolean;
+        };
+    };
+}
+/**
+ * A populate object reaching every component and dynamic zone of a schema, at
+ * any depth. Mappings live inside form components nested in dynamic zones —
+ * without deep populate they are simply absent from the entry and the audit
+ * would happily report a clean bill.
+ *
+ * Relations and media are deliberately not followed: mappings belong to the
+ * entry itself, and following relations would drag in unrelated documents.
+ */
+export declare function buildPopulate(components: Record<string, EntitySchema | undefined>, schema: EntitySchema, depth?: number): Record<string, unknown>;
+/** Something to show for an entry — better than a bare documentId when possible. */
+export declare function entryLabel(entry: Record<string, unknown>): string;
+export interface AuditEntry {
+    documentId: string;
+    locale?: string;
+    label: string;
+    problems: Problem[];
+}
+export interface AuditTargetReport {
+    uid: string;
+    /** Entries scanned, across locales. */
+    entries: number;
+    /** Mappings found in them. */
+    mappings: number;
+    invalid: AuditEntry[];
+    /** Set when the content type itself couldn't be scanned. */
+    error?: string;
+}
+export declare function runAudit(strapi: Core.Strapi, targets: ValidateTarget[], schema: Schema): Promise<AuditTargetReport[]>;
+export {};

package/dist/server/src/content-types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The dead-letter queue for submissions HubSpot couldn't take: transient
+ * failures land here after the in-process retries are exhausted, and
+ * `retryFailures()` replays them.
+ *
+ * Visible in the Content Manager on purpose — an admin can inspect a stuck
+ * payload and delete it — but hidden from the Content-Type Builder: its shape
+ * belongs to the plugin.
+ */
+declare const _default: {
+    failure: {
+        schema: {
+            kind: string;
+            collectionName: string;
+            info: {
+                singularName: string;
+                pluralName: string;
+                displayName: string;
+                description: string;
+            };
+            options: {
+                draftAndPublish: boolean;
+            };
+            pluginOptions: {
+                "content-manager": {
+                    visible: boolean;
+                };
+                "content-type-builder": {
+                    visible: boolean;
+                };
+            };
+            attributes: {
+                object: {
+                    type: string;
+                    required: boolean;
+                };
+                idProperty: {
+                    type: string;
+                    required: boolean;
+                };
+                properties: {
+                    type: string;
+                    required: boolean;
+                };
+                error: {
+                    type: string;
+                };
+                attempts: {
+                    type: string;
+                    default: number;
+                };
+            };
+        };
+    };
+};
+export default _default;