@bygghammar/cms-platform 0.80.1 → 0.90.0-m7.10

package/src/popups/cms-bridges.ts

@@ -0,0 +1,240 @@
+/**
+ * CMS-side discovery for the popup builder.
+ *
+ * The popup package has no idea what a form or a page is beyond a key and a
+ * path. These adapt what the CMS already knows into those neutral shapes, so
+ * every site using this platform gets working pickers without writing any of
+ * this itself.
+ */
+import type {
+  AdminNavigationPort,
+  AdminScreen,
+  FormDirectoryPort,
+  HostFormField,
+  HostFormSchema,
+  HostIntegrationTarget,
+  HostPage,
+  OptInDestinationPort,
+  PageDirectoryPort,
+} from "@bygghammar/lightweight-popup/adapters";
+import { fieldTypes } from "../forms/field-sets";
+import { backofficePaths } from "../backoffice/routes/host";
+import { DEFAULT_LOCALE, t } from "../i18n";
+import { backofficeHost } from "../backoffice/routes/host";
+
+type UnknownRecord = Record<string, unknown>;
+
+function asRecords(value: unknown): UnknownRecord[] {
+  return Array.isArray(value)
+    ? (value.filter(
+        (row) => typeof row === "object" && row !== null,
+      ) as UnknownRecord[])
+    : [];
+}
+
+function text(row: UnknownRecord, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = row[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return undefined;
+}
+
+/**
+ * The site's forms, from the backoffice host's own `listForms`.
+ *
+ * Only the key and a display name cross the boundary. The full row carries
+ * private settings — notification recipients, webhook secrets — that a popup
+ * builder has no business seeing.
+ */
+/**
+ * Field keys that are never a visitor's answer.
+ *
+ * The spam trap is the one that matters: it is a real field on a real form, and
+ * forwarding it would send a receiver evidence of the trap rather than anything
+ * anyone typed. The rest are identifiers and bookkeeping the form system owns.
+ */
+const NEVER_SENDABLE: ReadonlySet<string> = new Set([
+  "hp",
+  "honeypot",
+  "spam_honeypot",
+  "id",
+  "form_key",
+  "created_at",
+  "updated_at",
+  "ip",
+  "ip_address",
+  "user_agent",
+  "referrer",
+  "locale",
+  "client_token",
+  "submission_id",
+]);
+
+/** The human name for a field type, or nothing rather than a raw enum value. */
+function typeLabel(type: unknown): string | undefined {
+  if (typeof type !== "string") return undefined;
+  return fieldTypes().find((entry) => entry.value === type)?.label;
+}
+
+/**
+ * One stored field definition, as the popup builder needs to show it.
+ *
+ * Returns `null` for anything that is not a real, current answer: a field the
+ * editor disabled, one it removed (the key survives as a tombstone so old
+ * submissions still resolve a label), and anything on the list above.
+ */
+function toHostField(field: UnknownRecord): HostFormField | null {
+  const key = text(field, "key");
+  if (key === undefined) return null;
+  if (field["enabled"] === false) return null;
+  if (field["removed"] === true) return null;
+
+  const label = t(
+    (field["label"] ?? null) as never,
+    DEFAULT_LOCALE,
+  );
+  const type = typeLabel(field["type"]);
+  return {
+    key,
+    label: label.trim() === "" ? key : label,
+    ...(type === undefined ? {} : { type }),
+    sendable: !NEVER_SENDABLE.has(key),
+  };
+}
+
+export function cmsFormDirectory(): FormDirectoryPort {
+  const rows = async (): Promise<UnknownRecord[]> =>
+    asRecords(await backofficeHost().fns.listForms());
+
+  return {
+    listForms: async () => {
+      return (await rows()).flatMap((row) => {
+        const key = text(row, "key");
+        if (key === undefined) return [];
+        return [{ key, name: text(row, "name") ?? key }];
+      });
+    },
+
+    /*
+     * The same listing, read for its fields. No second host contract and no
+     * second query: `listForms` already returns each form's merged field
+     * definitions, which is what the forms screen itself renders from.
+     */
+    describeForms: async (keys): Promise<readonly HostFormSchema[]> => {
+      const wanted = new Set(keys);
+      return (await rows()).flatMap((row) => {
+        const key = text(row, "key");
+        if (key === undefined || !wanted.has(key)) return [];
+        const fields = asRecords(row["fields"])
+          .map(toHostField)
+          .filter((field): field is HostFormField => field !== null);
+        return [{ key, name: text(row, "name") ?? key, fields }];
+      });
+    },
+  };
+}
+
+/**
+ * The site's pages, for targeting.
+ *
+ * The popup builder shows an editor their pages by name and stores the
+ * address, so both halves have to be right. The name is the CMS's own page
+ * name. The address is the one a visitor would type — which is not the page's
+ * key: this platform's routing turns a key into a path through the site's slug
+ * table, and the home page is the case that proves it, since its key is
+ * `home` and its address is `/`. Targeting `/home` would match nothing, and
+ * nothing would say why.
+ *
+ * So a caller passes `resolvePath` — the routing engine the backoffice already
+ * uses for "view this page" links. Without one, the key is the best guess
+ * available, which is what this did before and is right for a host whose keys
+ * are paths.
+ *
+ * Returns an empty list rather than throwing when the host has no page module
+ * registered: a missing picker is a smaller problem than a backoffice screen
+ * that will not render.
+ */
+export function cmsPageDirectory(
+  resolvePath?: (pageKey: string) => string,
+): PageDirectoryPort {
+  return {
+    listPages: async (): Promise<readonly HostPage[]> => {
+      // `pages.fns.listPages` is the declared home for this. The top-level
+      // lookup stays for a site that registered it there before the contract
+      // named it, and a host with neither simply has no picker.
+      const host = backofficeHost();
+      const listPages =
+        host.pages?.fns.listPages ??
+        (host.fns as unknown as Record<string, unknown>)["listPages"];
+      if (typeof listPages !== "function") return [];
+      const rows = asRecords(await (listPages as () => Promise<unknown>)());
+      return rows.flatMap((row) => {
+        const key = text(row, "path", "slug", "key");
+        if (key === undefined) return [];
+        const resolved = resolvePath === undefined ? undefined : resolvePath(key);
+        const path =
+          resolved !== undefined && resolved.startsWith("/")
+            ? resolved
+            : key.startsWith("/")
+              ? key
+              : `/${key}`;
+        return [{ path, title: text(row, "title", "name") ?? path }];
+      });
+    },
+  };
+}
+
+/**
+ * The site's opt-in destinations, for the popup editor's picker.
+ *
+ * Only an id, a name and a warning cross the boundary. The endpoint and the
+ * signing secret stay on the server: a popup's configuration is readable by
+ * anyone who can read active popups, so anything more would be published.
+ *
+ * A host with no destination integration gets an empty list rather than an
+ * error, and the popup editor then shows no picker at all.
+ */
+export function cmsOptInDestinations(): OptInDestinationPort {
+  return {
+    listDestinations: async (): Promise<readonly HostIntegrationTarget[]> => {
+      const host = backofficeHost() as unknown as {
+        fns: Record<string, unknown>;
+      };
+      const list = host.fns["listWebhookDestinations"];
+      if (typeof list !== "function") return [];
+
+      const rows = asRecords(await (list as () => Promise<unknown>)());
+      return rows.flatMap((row) => {
+        const id = text(row, "id");
+        if (id === undefined) return [];
+        const name = text(row, "name") ?? id;
+        // A destination whose secret is missing from this environment will fail
+        // at delivery time. Saying so in the picker beats a silent failure.
+        const configured = row["secretConfigured"];
+        const warning =
+          configured === false
+            ? "its signing secret is not set in this environment"
+            : undefined;
+        return [{ id, name, ...(warning === undefined ? {} : { warning }) }];
+      });
+    },
+  };
+}
+
+
+/**
+ * Where this site mounted the popup screens.
+ *
+ * Derived from the backoffice base the site configured, like every other
+ * backoffice path — so a site that moves its backoffice moves these with it,
+ * and the popup package never learns either address.
+ */
+export function cmsPopupNavigation(current: AdminScreen): AdminNavigationPort {
+  const paths = backofficePaths();
+  return {
+    popupsHref: paths.popups,
+    destinationsHref: paths.popupDestinations,
+    current,
+  };
+}

package/src/popups/destinations.tsx

@@ -0,0 +1,147 @@
+/**
+ * The opt-in destinations screen, bound to the host's server functions.
+ *
+ * The screen itself belongs to the popup package and is provider-neutral;
+ * this is the thin adapter that turns its port into the host's own calls.
+ * Every one of those calls is staff-guarded on the server — nothing here
+ * grants access, it only routes.
+ */
+import type { ReactNode } from "react";
+
+import { DestinationsAdmin } from "@bygghammar/lightweight-popup/admin";
+// The same stylesheet the popup builder imports. This screen is a sibling
+// route, not a child of it, so it loads on its own and has to ask for its own
+// styling — without this it renders as unstyled text, which is exactly what it
+// did the first time anyone could reach it.
+import "@bygghammar/lightweight-popup/admin.css";
+import type {
+  DeliveryRecord,
+  DestinationDraft,
+  DestinationRecord,
+  OptInDestinationAdminPort,
+  TestDeliveryOutcome,
+} from "@bygghammar/lightweight-popup/adapters";
+
+import { backofficeHost } from "../backoffice/routes/host";
+import { cmsPopupNavigation } from "./cms-bridges";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Fn = (...args: any[]) => Promise<any>;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+function hostFn(name: string): Fn | undefined {
+  const host = backofficeHost() as unknown as { fns: Record<string, unknown> };
+  const fn = host.fns[name];
+  return typeof fn === "function" ? (fn as Fn) : undefined;
+}
+
+/**
+ * A host that has not registered these functions gets an empty, honest
+ * screen rather than a crash: the site simply has no delivery integration.
+ */
+export function cmsDestinationAdmin(): OptInDestinationAdminPort {
+  return {
+    list: async (): Promise<readonly DestinationRecord[]> => {
+      const fn = hostFn("listWebhookDestinations");
+      if (fn === undefined) return [];
+      return (await fn()) as DestinationRecord[];
+    },
+
+    save: async (draft: DestinationDraft) => {
+      const fn = hostFn("saveWebhookDestination");
+      if (fn === undefined)
+        return {
+          ok: false as const,
+          error: "This site cannot save destinations.",
+        };
+      return (await fn({ data: draft })) as
+        { ok: true; id: string } | { ok: false; error: string };
+    },
+
+    setEnabled: async (id: string, enabled: boolean): Promise<void> => {
+      // Enabling is an ordinary save of one field, so there is no second
+      // server contract to keep in step with the first.
+      const list = hostFn("listWebhookDestinations");
+      const save = hostFn("saveWebhookDestination");
+      if (list === undefined || save === undefined) return;
+      const rows = (await list()) as DestinationRecord[];
+      const row = rows.find((candidate) => candidate.id === id);
+      if (row === undefined) return;
+      await save({
+        data: {
+          id,
+          name: row.name,
+          // Empty means "keep the stored endpoint": the display value has its
+          // query string removed and must never be written back as the real one.
+          endpoint: "",
+          secretRefName: row.secretRefName ?? "",
+          fields: [...row.fields],
+          isActive: enabled,
+          description: row.description,
+        },
+      });
+    },
+
+    remove: async (id: string): Promise<void> => {
+      const fn = hostFn("deleteWebhookDestination");
+      if (fn === undefined) return;
+      await fn({ data: { id } });
+    },
+
+    sendTest: async (id: string): Promise<TestDeliveryOutcome> => {
+      const fn = hostFn("sendTestWebhook");
+      if (fn === undefined) return { ok: false, category: "config-error" };
+      const result = (await fn({ data: { destinationId: id } })) as {
+        ok?: unknown;
+        category?: unknown;
+      };
+      if (result.ok === true) return { ok: true };
+      /*
+       * A host that names no category has told us nothing about where this
+       * failed. Defaulting to "http-error" claimed the endpoint refused the
+       * request — which sent administrators to debug a receiver that had never
+       * been contacted, because a missing signing secret arrives this way.
+       * "config-error" is the honest answer to "something went wrong here".
+       */
+      return {
+        ok: false,
+        category:
+          typeof result.category === "string" && result.category !== ""
+            ? result.category
+            : "config-error",
+      };
+    },
+
+    listDeliveries: async (): Promise<readonly DeliveryRecord[]> => {
+      const fn = hostFn("listWebhookDeliveries");
+      if (fn === undefined) return [];
+      const rows = (await fn({ data: {} })) as Record<string, unknown>[];
+      return rows.map((row) => ({
+        id: String(row["id"]),
+        popupKey: String(row["popup_key"] ?? ""),
+        status: String(row["status"] ?? "pending"),
+        attempts: Number(row["attempts"] ?? 0),
+        httpStatus:
+          typeof row["last_status"] === "number" ? row["last_status"] : null,
+        errorCategory:
+          typeof row["last_error_category"] === "string"
+            ? row["last_error_category"]
+            : null,
+        isTest: row["is_test"] === true,
+        createdAt: String(row["created_at"] ?? ""),
+      }));
+    },
+  };
+}
+
+/** The screen, ready to mount on a route. */
+export function PopupDestinationsView(): ReactNode {
+  return (
+    <DestinationsAdmin
+      destinations={cmsDestinationAdmin()}
+      navigation={cmsPopupNavigation("destinations")}
+    />
+  );
+}
+
+export default PopupDestinationsView;

package/src/popups/host.ts

@@ -0,0 +1,91 @@
+/**
+ * What a site must supply for the Popups module.
+ *
+ * Deliberately small and provider-neutral: the CMS integration knows nothing
+ * about Supabase, PostgREST, RLS or a connection string. A site registers
+ * repositories that speak the popup package's own contracts, and everything
+ * provider-specific stays on the site's side of this boundary.
+ */
+import type {
+  AnalyticsEventRepository,
+  FormDirectoryPort,
+  PageDirectoryPort,
+  PopupAdminRepository,
+  PopupConfigRepository,
+  PopupStatisticsRepository,
+} from "@bygghammar/lightweight-popup/adapters";
+
+/** Repositories the public runtime needs. Read and append only. */
+export type PopupPublicHost = {
+  readonly configs: PopupConfigRepository;
+  readonly analytics: AnalyticsEventRepository;
+  /**
+   * Paths of the site's own that no popup may appear on.
+   *
+   * The backoffice is added for every site already, from the configured
+   * `backofficePath` — this is for the rest: a checkout, a members' area, a
+   * page a site simply wants left alone. Patterns are the popup package's:
+   * `/checkout` for one page, `/checkout/**` for everything beneath it.
+   */
+  readonly excludedPaths?: readonly string[];
+};
+
+/**
+ * Repositories the backoffice needs, in addition to the public ones.
+ *
+ * Form and page discovery are optional here because the CMS supplies them
+ * itself — a host only overrides them if its content model differs from the
+ * platform's.
+ */
+export type PopupAdminHost = {
+  readonly popups: PopupAdminRepository;
+  readonly statistics: PopupStatisticsRepository;
+  readonly formDirectory?: FormDirectoryPort;
+  readonly pages?: PageDirectoryPort;
+};
+
+let publicHost: PopupPublicHost | null = null;
+let adminHost: PopupAdminHost | null = null;
+
+/**
+ * Register the site's public popup repositories.
+ *
+ * Called from a site's public bundle. Keeping this separate from the admin
+ * registration is what lets the public site avoid importing anything the
+ * backoffice needs.
+ */
+export function registerPopupPublicHost(
+  host: PopupPublicHost,
+): PopupPublicHost {
+  publicHost = host;
+  return host;
+}
+
+export function registerPopupAdminHost(host: PopupAdminHost): PopupAdminHost {
+  adminHost = host;
+  return host;
+}
+
+export function popupPublicHost(): PopupPublicHost {
+  if (publicHost === null) {
+    throw new Error(
+      "@bygghammar/cms-platform: the Popups module is enabled but no public host is registered. Call registerPopupPublicHost() during site startup.",
+    );
+  }
+  return publicHost;
+}
+
+export function popupAdminHost(): PopupAdminHost {
+  if (adminHost === null) {
+    throw new Error(
+      "@bygghammar/cms-platform: the Popups backoffice is mounted but no admin host is registered. Call registerPopupAdminHost() from the backoffice entry.",
+    );
+  }
+  return adminHost;
+}
+
+/** Test helper. */
+export function clearPopupHosts(): void {
+  publicHost = null;
+  adminHost = null;
+}

package/src/popups/media-bridge.tsx

@@ -0,0 +1,84 @@
+/**
+ * The CMS media library, offered to the popup builder.
+ *
+ * This is the whole bridge: the popup package asks a host to render a picker,
+ * and the host renders the same `MediaPickerDialog` every other CMS screen
+ * uses. Nothing is reimplemented — the library's browsing, searching and
+ * uploading all come along, because it is literally the same component.
+ *
+ * What crosses the boundary is a URL, a filename and (when the library knows
+ * one) alt text. The popup package never learns which storage provider the
+ * site uses, and never uploads anything itself.
+ */
+import type { ReactNode } from "react";
+
+import type {
+  HostMediaItem,
+  MediaPickerPort,
+} from "@bygghammar/lightweight-popup/adapters";
+
+import { MediaPickerDialog } from "../backoffice/inspectors/fields";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * What the picker hands back.
+ *
+ * Structural rather than the library's own type: the shape has grown fields
+ * over time and a popup needs three of them.
+ */
+type PickedItem = {
+  url?: unknown;
+  name?: unknown;
+  path?: unknown;
+  alt?: unknown;
+} & Record<string, any>;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+/**
+ * Turn one library item into the neutral shape the popup package stores.
+ *
+ * `url` is the stable public address the media library already serves to the
+ * site — the same value every other block stores — so a popup configured in
+ * one environment keeps working in the next. A signed or expiring link would
+ * render today and 404 later, which the package's own reference check refuses
+ * anyway.
+ */
+export function toHostMediaItem(item: PickedItem): HostMediaItem | null {
+  const src = text(item.url) ?? text(item.path);
+  if (src === undefined) return null;
+  const name = text(item.name);
+  const alt = text(item.alt);
+  return {
+    src,
+    ...(name === undefined ? {} : { name }),
+    ...(alt === undefined ? {} : { alt }),
+  };
+}
+
+/**
+ * The site's media library as a popup media port.
+ *
+ * Images only: a popup's picture is a picture, and offering video here would
+ * put a file in an `<img>` that cannot render it.
+ */
+export function cmsMediaPicker(): MediaPickerPort {
+  return {
+    renderPicker: ({ onPick, onClose }): ReactNode => (
+      <MediaPickerDialog
+        accept="image"
+        onPick={(item) => {
+          const media = toHostMediaItem(item as PickedItem);
+          // A library row with no address is not something to hand on; closing
+          // is honest, and the editor keeps whatever they had.
+          if (media !== null) onPick(media);
+          onClose();
+        }}
+        onClose={onClose}
+      />
+    ),
+  };
+}

package/src/popups/register.ts

@@ -0,0 +1,23 @@
+/**
+ * Registers the Popups module's loaders.
+ *
+ * Deliberately tiny and free of popup imports: a site calls this once, and
+ * nothing about the popup runtime — not the package, not its CSS, not the
+ * builder — is evaluated until the module is both enabled and hydrated. The
+ * `import()` calls below are ordinary local imports the host's bundler turns
+ * into separate chunks; nothing is fetched from a remote origin.
+ *
+ * An explicit function rather than a module-scope side effect: a host whose
+ * `sideEffects` field is an allowlist tree-shakes a bare
+ * `import "…/popups/register"` away, taking the registration with it, and the
+ * build still succeeds. That failure is silent — no popup ever appears.
+ */
+import {
+  registerModuleAdmin,
+  registerModuleRuntime,
+} from "../modules/public-runtime";
+
+export function registerPopupModule(): void {
+  registerModuleRuntime("popups", () => import("./runtime"));
+  registerModuleAdmin("popups", () => import("./admin"));
+}