@carlonicora/nextjs-jsonapi 3.11.0 → 3.13.0

package/src/features/billing/stripe-price/data/__tests__/stripe-price.transfer.spec.ts

@@ -0,0 +1,265 @@
+import { describe, expect, it } from "vitest";
+import { StripePriceInterface } from "../stripe-price.interface";
+import {
+  STRIPE_PRICE_TRANSFER_KIND,
+  STRIPE_PRICE_TRANSFER_VERSION,
+  buildStripePriceTransferDocument,
+  parseStripePriceTransferDocument,
+  priceToSeed,
+  stripePriceTransferFilename,
+} from "../stripe-price.transfer";
+
+// A plain object, never the real model: the model's `currency` / `priceType`
+// getters throw when the attribute is absent, and the point of these tests is
+// the transformation, not the hydration.
+const makePrice = (overrides: Partial<Record<keyof StripePriceInterface, unknown>> = {}): StripePriceInterface =>
+  ({
+    id: "price-node-1",
+    stripePriceId: "price_1SourceEnv",
+    productId: "product-node-1",
+    active: true,
+    currency: "eur",
+    unitAmount: 5900,
+    priceType: "recurring",
+    recurring: { interval: "month", intervalCount: 1, usageType: "licensed" },
+    nickname: "Standard",
+    lookupKey: "standard_monthly",
+    metadata: { env: "production" },
+    description: "The standard plan",
+    features: ["Unlimited projects", "Priority support"],
+    token: 1000,
+    isTrial: false,
+    priceFeatures: [{ id: "feature-node-9", name: "AI assistant" }],
+    ...overrides,
+  }) as unknown as StripePriceInterface;
+
+describe("stripe-price.transfer", () => {
+  describe("priceToSeed", () => {
+    it("carries no identity across environments", () => {
+      const seed = priceToSeed(makePrice());
+
+      expect(seed).not.toHaveProperty("id");
+      expect(seed).not.toHaveProperty("stripePriceId");
+      expect(seed).not.toHaveProperty("productId");
+      expect(seed).not.toHaveProperty("active");
+      expect(seed).not.toHaveProperty("lookupKey");
+      expect(seed).not.toHaveProperty("metadata");
+    });
+
+    it("keeps unitAmount in minor units", () => {
+      expect(priceToSeed(makePrice({ unitAmount: 5900 })).unitAmount).toBe(5900);
+    });
+
+    it("defaults a missing unitAmount to 0", () => {
+      expect(priceToSeed(makePrice({ unitAmount: undefined })).unitAmount).toBe(0);
+    });
+
+    it("exports platform features by NAME, never by id", () => {
+      const seed = priceToSeed(
+        makePrice({
+          priceFeatures: [
+            { id: "feature-node-9", name: "AI assistant" },
+            { id: "feature-node-3", name: "Custom domains" },
+          ],
+        }),
+      );
+
+      expect(seed.platformFeatures).toEqual(["AI assistant", "Custom domains"]);
+    });
+
+    it("omits platformFeatures entirely when the price has none", () => {
+      const seed = priceToSeed(makePrice({ priceFeatures: [] }));
+
+      expect(seed).not.toHaveProperty("platformFeatures");
+    });
+
+    it("exports interval 'one_time' for a one-time price", () => {
+      const seed = priceToSeed(makePrice({ priceType: "one_time", recurring: undefined }));
+
+      expect(seed.interval).toBe("one_time");
+      expect(seed).not.toHaveProperty("intervalCount");
+      expect(seed).not.toHaveProperty("usageType");
+    });
+
+    it("falls back to a monthly interval when a recurring price has no recurring block", () => {
+      const seed = priceToSeed(makePrice({ priceType: "recurring", recurring: undefined }));
+
+      expect(seed.interval).toBe("month");
+    });
+
+    it("keeps a token of 0, which means 'no AI' rather than 'unset'", () => {
+      expect(priceToSeed(makePrice({ token: 0 })).token).toBe(0);
+    });
+
+    it("omits optional keys instead of writing undefined", () => {
+      const seed = priceToSeed(
+        makePrice({
+          nickname: undefined,
+          description: "",
+          features: [],
+          token: undefined,
+          isTrial: undefined,
+        }),
+      );
+
+      expect(Object.keys(seed).sort()).toEqual(
+        ["currency", "interval", "intervalCount", "platformFeatures", "unitAmount", "usageType"].sort(),
+      );
+      expect(JSON.stringify(seed)).not.toContain("undefined");
+    });
+
+    it("survives a model whose currency and priceType getters throw", () => {
+      const throwing = {
+        get currency(): string {
+          throw new Error("currency is not defined");
+        },
+        get priceType(): "one_time" | "recurring" {
+          throw new Error("priceType is not defined");
+        },
+        unitAmount: 1500,
+        recurring: { interval: "year", intervalCount: 1 },
+        priceFeatures: [],
+      } as unknown as StripePriceInterface;
+
+      expect(priceToSeed(throwing)).toEqual({ unitAmount: 1500, currency: "usd", interval: "year", intervalCount: 1 });
+    });
+  });
+
+  describe("buildStripePriceTransferDocument", () => {
+    it("round-trips through JSON unchanged", () => {
+      const document = buildStripePriceTransferDocument(makePrice());
+
+      const parsed = parseStripePriceTransferDocument(JSON.stringify(document));
+
+      expect(parsed).toEqual(document);
+      expect(parsed.price).toEqual(document.price);
+      expect(parsed.kind).toBe(STRIPE_PRICE_TRANSFER_KIND);
+      expect(parsed.version).toBe(STRIPE_PRICE_TRANSFER_VERSION);
+    });
+
+    it("serialises no identity at all", () => {
+      const serialised = JSON.stringify(buildStripePriceTransferDocument(makePrice()));
+
+      expect(serialised).not.toContain("stripePriceId");
+      expect(serialised).not.toContain("price_1SourceEnv");
+      expect(serialised).not.toContain("productId");
+      expect(serialised).not.toContain("product-node-1");
+      expect(serialised).not.toContain("price-node-1");
+      expect(serialised).not.toContain("feature-node-9");
+      expect(serialised).not.toContain("lookupKey");
+      expect(serialised).not.toContain("metadata");
+      expect(serialised).not.toMatch(/"id"/);
+    });
+  });
+
+  describe("stripePriceTransferFilename", () => {
+    it("slugs the nickname", () => {
+      expect(stripePriceTransferFilename(makePrice({ nickname: "Standard" }))).toBe("price-standard.json");
+    });
+
+    it("collapses non-alphanumerics and trims the edges", () => {
+      expect(stripePriceTransferFilename(makePrice({ nickname: "  Pro // Yearly (EU)!  " }))).toBe(
+        "price-pro-yearly-eu.json",
+      );
+    });
+
+    it("falls back to amount and currency without a nickname", () => {
+      expect(stripePriceTransferFilename(makePrice({ nickname: undefined, unitAmount: 5900, currency: "eur" }))).toBe(
+        "price-5900-eur.json",
+      );
+    });
+
+    it("never emits a path separator", () => {
+      const filename = stripePriceTransferFilename(makePrice({ nickname: "../../etc/passwd" }));
+
+      expect(filename).not.toContain("/");
+      expect(filename).not.toContain("\\");
+      expect(filename).toBe("price-etc-passwd.json");
+    });
+  });
+
+  describe("parseStripePriceTransferDocument", () => {
+    const validDocument = () => ({
+      kind: STRIPE_PRICE_TRANSFER_KIND,
+      version: STRIPE_PRICE_TRANSFER_VERSION,
+      price: { unitAmount: 5900, currency: "eur", interval: "month" },
+    });
+
+    it("rejects text that is not JSON", () => {
+      expect(() => parseStripePriceTransferDocument("not json at all")).toThrow(/not valid JSON/i);
+    });
+
+    it("rejects a wrong kind", () => {
+      const raw = JSON.stringify({ ...validDocument(), kind: "stripe-product" });
+
+      expect(() => parseStripePriceTransferDocument(raw)).toThrow(/kind/i);
+    });
+
+    it("rejects a future version", () => {
+      const raw = JSON.stringify({ ...validDocument(), version: 99 });
+
+      expect(() => parseStripePriceTransferDocument(raw)).toThrow(/version/i);
+    });
+
+    it("rejects a missing unitAmount", () => {
+      const raw = JSON.stringify({ ...validDocument(), price: { currency: "eur", interval: "month" } });
+
+      expect(() => parseStripePriceTransferDocument(raw)).toThrow(/unitAmount/);
+    });
+
+    it("rejects a negative unitAmount and an unknown interval", () => {
+      expect(() =>
+        parseStripePriceTransferDocument(
+          JSON.stringify({ ...validDocument(), price: { unitAmount: -1, currency: "eur", interval: "month" } }),
+        ),
+      ).toThrow(/unitAmount/);
+
+      expect(() =>
+        parseStripePriceTransferDocument(
+          JSON.stringify({ ...validDocument(), price: { unitAmount: 100, currency: "eur", interval: "fortnight" } }),
+        ),
+      ).toThrow(/interval/);
+    });
+
+    it("strips unknown keys instead of failing on them", () => {
+      const raw = JSON.stringify({
+        ...validDocument(),
+        price: {
+          unitAmount: 5900,
+          currency: "eur",
+          interval: "month",
+          stripePriceId: "price_1OtherEnv",
+          productId: "product-node-2",
+          id: "price-node-2",
+        },
+      });
+
+      const parsed = parseStripePriceTransferDocument(raw);
+
+      expect(parsed.price).toEqual({ unitAmount: 5900, currency: "eur", interval: "month" });
+      expect(parsed.price).not.toHaveProperty("stripePriceId");
+      expect(parsed.price).not.toHaveProperty("productId");
+      expect(parsed.price).not.toHaveProperty("id");
+    });
+
+    it("keeps every optional key it recognises", () => {
+      const price = {
+        unitAmount: 5900,
+        currency: "eur",
+        interval: "year",
+        intervalCount: 2,
+        usageType: "metered",
+        nickname: "Standard",
+        description: "The standard plan",
+        features: ["Unlimited projects"],
+        token: 0,
+        isTrial: true,
+        platformFeatures: ["AI assistant"],
+      };
+
+      const parsed = parseStripePriceTransferDocument(JSON.stringify({ ...validDocument(), price }));
+
+      expect(parsed.price).toEqual(price);
+    });
+  });
+});

package/src/features/billing/stripe-price/data/stripe-price.fields.ts

@@ -5,4 +5,5 @@ export enum StripePriceFields {
   interval = "interval",
   token = "token",
   status = "status",
+  actions = "actions",
 }

package/src/features/billing/stripe-price/data/stripe-price.transfer.ts

@@ -0,0 +1,194 @@
+import { z } from "zod";
+import { StripePriceInterface } from "./stripe-price.interface";
+
+// ============================================================================
+// Stripe Price Transfer Document
+// ----------------------------------------------------------------------------
+// Pure, DOM-free: no React, no window, no Blob, no fetch. Everything here is a
+// plain data transformation so it can be unit-tested without a renderer, and so
+// both the export (download) and the clone (prefill an editor) paths can share
+// one definition of "the editable shape of a price".
+// ============================================================================
+
+export const STRIPE_PRICE_TRANSFER_KIND = "stripe-price";
+export const STRIPE_PRICE_TRANSFER_VERSION = 1;
+
+/** Versions this build can still read. Older documents stay parseable here. */
+const SUPPORTED_VERSIONS: number[] = [STRIPE_PRICE_TRANSFER_VERSION];
+
+/** The editable shape of a price, portable between environments. */
+export type StripePriceSeed = {
+  unitAmount: number; // MINOR units (cents), exactly as Stripe stores it
+  currency: string;
+  interval: "one_time" | "day" | "week" | "month" | "year";
+  intervalCount?: number;
+  usageType?: "licensed" | "metered";
+  nickname?: string;
+  description?: string;
+  features?: string[]; // free-text marketing bullets
+  token?: number;
+  isTrial?: boolean;
+  platformFeatures?: string[]; // Feature entity NAMES (never ids — ids differ per environment)
+};
+
+export type StripePriceTransferDocument = {
+  kind: typeof STRIPE_PRICE_TRANSFER_KIND;
+  version: typeof STRIPE_PRICE_TRANSFER_VERSION;
+  price: StripePriceSeed;
+};
+
+const seedSchema = z.object({
+  unitAmount: z.number().min(0),
+  currency: z.string().min(1),
+  interval: z.enum(["one_time", "day", "week", "month", "year"]),
+  intervalCount: z.number().min(1).optional(),
+  usageType: z.enum(["licensed", "metered"]).optional(),
+  nickname: z.string().optional(),
+  description: z.string().optional(),
+  features: z.array(z.string()).optional(),
+  token: z.number().optional(),
+  isTrial: z.boolean().optional(),
+  platformFeatures: z.array(z.string()).optional(),
+});
+
+/**
+ * `currency` and `priceType` are getters that THROW when the attribute is
+ * absent (stripe-price.ts:42-58), and `productId` demonstrably is absent on a
+ * hydrated price (see the note in PriceEditor). Read anything model-backed
+ * through here so a partially-hydrated price degrades to a default instead of
+ * exploding mid-export.
+ */
+function readOptional<T>(read: () => T): T | undefined {
+  try {
+    return read();
+  } catch {
+    return undefined;
+  }
+}
+
+function nonEmptyStrings(values: string[] | undefined): string[] {
+  if (!Array.isArray(values)) return [];
+  return values.map((value) => value.trim()).filter((value) => value.length > 0);
+}
+
+/**
+ * Clone path: a live price -> the editable seed.
+ *
+ * Carries NO identity: no id, no stripePriceId, no productId, no active, no
+ * lookupKey, no metadata. A clone is a brand-new Stripe price and Stripe mints
+ * its own id on create; copying any of those across would either collide or
+ * silently re-point the new price at the source environment's objects.
+ */
+export function priceToSeed(price: StripePriceInterface): StripePriceSeed {
+  const priceType = readOptional(() => price.priceType);
+  const currency = readOptional(() => price.currency);
+  const recurring = price.recurring;
+
+  // Same derivation as PriceEditor's getDefaultValues, so a cloned seed and the
+  // form it prefills never disagree about what interval a price has.
+  const interval: StripePriceSeed["interval"] =
+    priceType === "one_time" ? "one_time" : (recurring?.interval ?? "month");
+
+  // MINOR units on purpose. PriceEditor divides by 100 for display; the
+  // document stays in the unit Stripe itself stores.
+  const seed: StripePriceSeed = {
+    unitAmount: price.unitAmount ?? 0,
+    currency: currency ?? "usd",
+    interval,
+  };
+
+  if (interval !== "one_time") {
+    if (typeof recurring?.intervalCount === "number") seed.intervalCount = recurring.intervalCount;
+    if (recurring?.usageType) seed.usageType = recurring.usageType;
+  }
+
+  const nickname = price.nickname?.trim();
+  if (nickname) seed.nickname = nickname;
+
+  const description = price.description?.trim();
+  if (description) seed.description = description;
+
+  const features = nonEmptyStrings(price.features);
+  if (features.length > 0) seed.features = features;
+
+  // `0` is a meaningful token value ("no AI"), so test for the type, never for
+  // truthiness.
+  if (typeof price.token === "number" && !Number.isNaN(price.token)) seed.token = price.token;
+
+  if (typeof price.isTrial === "boolean") seed.isTrial = price.isTrial;
+
+  // NAMES, never ids: Feature ids differ per environment, names are the stable
+  // handle an importing environment can resolve against its own Feature rows.
+  const platformFeatures = nonEmptyStrings(price.priceFeatures?.map((feature) => feature.name));
+  if (platformFeatures.length > 0) seed.platformFeatures = platformFeatures;
+
+  return seed;
+}
+
+/** Export path. */
+export function buildStripePriceTransferDocument(price: StripePriceInterface): StripePriceTransferDocument {
+  return {
+    kind: STRIPE_PRICE_TRANSFER_KIND,
+    version: STRIPE_PRICE_TRANSFER_VERSION,
+    price: priceToSeed(price),
+  };
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** Export path: a safe download filename, e.g. "price-standard.json". */
+export function stripePriceTransferFilename(price: StripePriceInterface): string {
+  const seed = priceToSeed(price);
+  const fromNickname = seed.nickname ? slugify(seed.nickname) : "";
+  // Fallback keeps two exports of different prices from colliding when neither
+  // is nicknamed. Both halves are slugified, so no separator can survive.
+  const slug = fromNickname || slugify(`${seed.unitAmount}-${seed.currency}`);
+
+  return `price-${slug || "export"}.json`;
+}
+
+/** Import path. Throws an Error when the text is not a valid document. */
+export function parseStripePriceTransferDocument(raw: string): StripePriceTransferDocument {
+  let candidate: unknown;
+  try {
+    candidate = JSON.parse(raw);
+  } catch {
+    throw new Error("The file is not valid JSON.");
+  }
+
+  if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate))
+    throw new Error("The file is not a price transfer document.");
+
+  const document = candidate as Record<string, unknown>;
+
+  if (document.kind !== STRIPE_PRICE_TRANSFER_KIND)
+    throw new Error(
+      `The file is not a price transfer document: expected kind "${STRIPE_PRICE_TRANSFER_KIND}", found ${JSON.stringify(document.kind)}.`,
+    );
+
+  if (typeof document.version !== "number" || !SUPPORTED_VERSIONS.includes(document.version))
+    throw new Error(
+      `Unsupported price transfer version ${JSON.stringify(document.version)}. Supported: ${SUPPORTED_VERSIONS.join(", ")}.`,
+    );
+
+  // Unknown keys are stripped rather than rejected, so a document written by a
+  // newer build of the same version still imports.
+  const parsed = seedSchema.safeParse(document.price);
+  if (!parsed.success) {
+    const details = parsed.error.issues
+      .map((issue) => `${issue.path.join(".") || "price"}: ${issue.message}`)
+      .join("; ");
+    throw new Error(`The price in the file is not valid. ${details}`);
+  }
+
+  return {
+    kind: STRIPE_PRICE_TRANSFER_KIND,
+    version: STRIPE_PRICE_TRANSFER_VERSION,
+    price: parsed.data,
+  };
+}

package/src/features/billing/stripe-price/hooks/useStripePriceTableStructure.tsx

@@ -1,21 +1,41 @@
 "use client";
 
 import { ColumnDef } from "@tanstack/react-table";
+import { CopyIcon, DownloadIcon } from "lucide-react";
 import { useTranslations } from "next-intl";
 import { useMemo } from "react";
 import { Modules } from "../../../../core";
 import { registerTableGenerator, TableContent, usePageUrlGenerator, UseTableStructureHook } from "../../../../hooks";
-import { Badge, Link } from "../../../../shadcnui";
+import { Badge, Button, Link } from "../../../../shadcnui";
 import { formatCurrency, formatInterval } from "../../components/utils/currency";
 import { StripePriceFields } from "../data/stripe-price.fields";
 import { StripePriceInterface } from "../data/stripe-price.interface";
 
+/**
+ * Row-level handlers the ACTIONS column calls. They reach this hook through
+ * `ContentListTable`'s `context` prop, which the table forwards verbatim as
+ * `params.context` (ContentListTable.tsx:88-95, hooks/types.ts:27) — the table
+ * generator registry hands the hook nothing else from the call site.
+ *
+ * Both are optional on purpose: the same generator serves lists that render the
+ * actions column without wiring anything (or that omit the column entirely), so
+ * each button is rendered only when its handler is actually present rather than
+ * rendering a dead control.
+ */
+type StripePriceRowActions = {
+  onClone?: (price: StripePriceInterface) => void;
+  onExport?: (price: StripePriceInterface) => void;
+};
+
 export const useStripePriceTableStructure: UseTableStructureHook<StripePriceInterface, StripePriceFields> = (
   params,
 ) => {
   const t = useTranslations();
   const generateUrl = usePageUrlGenerator();
 
+  const onClone = params.context?.onClone as StripePriceRowActions["onClone"];
+  const onExport = params.context?.onExport as StripePriceRowActions["onExport"];
+
   const tableData = useMemo(() => {
     return params.data.map((price: StripePriceInterface) => {
       const entry: TableContent<StripePriceInterface> = { jsonApiData: price };
@@ -105,13 +125,57 @@ export const useStripePriceTableStructure: UseTableStructureHook<StripePriceInte
       enableSorting: false,
       enableHiding: false,
     }),
+    [StripePriceFields.actions]: () => ({
+      id: "actions",
+      accessorKey: "actions",
+      header: t("billing.admin.prices.fields.actions"),
+      cell: ({ row }: { row: TableContent<StripePriceInterface> }) => {
+        const price: StripePriceInterface = row.original.jsonApiData;
+        return (
+          <span className="flex items-center justify-end gap-x-1">
+            {onClone && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                aria-label={t("billing.admin.prices.actions.clone")}
+                onClick={(event) => {
+                  // The row itself can be clickable (ContentListTable's
+                  // `onRowClick`), so a row action must never bubble into it.
+                  event.stopPropagation();
+                  onClone(price);
+                }}
+              >
+                <CopyIcon />
+              </Button>
+            )}
+            {onExport && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                aria-label={t("billing.admin.prices.actions.export")}
+                onClick={(event) => {
+                  event.stopPropagation();
+                  onExport(price);
+                }}
+              >
+                <DownloadIcon />
+              </Button>
+            )}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
   };
 
   const columns = useMemo(() => {
     return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
       TableContent<StripePriceInterface>
     >[];
-  }, [params.fields, fieldColumnMap, t, generateUrl]);
+  }, [params.fields, fieldColumnMap, t, generateUrl, onClone, onExport]);
 
   return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
 };

package/src/features/content/data/content.interface.ts

@@ -5,7 +5,7 @@ export type ContentInput = {
   id: string;
   name?: string;
 
-  authorId: string;
+  authorId?: string;
   editorIds?: string[];
 };
 

package/src/features/handbook/HandbookPageModule.ts

@@ -0,0 +1,41 @@
+import { BookOpenIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookPage } from "./data/HandbookPage";
+
+export const HandbookPageModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "b1f1c2d6-6a0e-4e93-9b6d-3f5f4a2c81e7",
+    pageUrl: "/administration/handbook",
+    name: "handbookpages",
+    model: HandbookPage,
+    icon: BookOpenIcon,
+    inclusions: {
+      lists: {
+        // `content` is deliberately omitted: the list renders titles and
+        // status, and a thousand pages of markdown do not belong in a list
+        // payload. `section`, `order` and `summary` are the index fields the
+        // contents page groups, orders and describes pages by, so they are the
+        // one part of the payload the list surface cannot do without.
+        //
+        // `displayTitle` and `displaySummary` are the translated halves of the
+        // two strings the contents page prints, and a sparse fieldset that
+        // omitted them would leave every row in English. `displayContent` is
+        // NOT here for the same reason `content` is not: it is the whole
+        // markdown body, and it belongs to the detail read alone.
+        fields: [
+          createJsonApiInclusion("handbookpages", [
+            "path",
+            "title",
+            "displayTitle",
+            "section",
+            "order",
+            "summary",
+            "displaySummary",
+            "wordCount",
+            "aiStatus",
+          ]),
+        ],
+      },
+    },
+  });

package/src/features/handbook/HandbookSectionModule.ts

@@ -0,0 +1,35 @@
+import { LibraryIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookSection } from "./data/HandbookSection";
+
+/**
+ * One top-level directory of the documentation tree. Like the thread message,
+ * it has no `pageUrl` — a section has no page of its own; it is a heading on
+ * the contents surface and nothing more.
+ */
+export const HandbookSectionModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "6b0a2f74-1c53-4a0e-9c1d-2e7b4a9d6f30",
+    name: "handbooksections",
+    model: HandbookSection,
+    icon: LibraryIcon,
+    inclusions: {
+      lists: {
+        // `HandbookSectionService.findMany` is the ONLY read of this resource and
+        // it limits to these fields, so the translated halves have to be here:
+        // without them every section heading on the contents page and in the
+        // reader's navigator would stay English however good the translation is.
+        fields: [
+          createJsonApiInclusion("handbooksections", [
+            "key",
+            "title",
+            "displayTitle",
+            "summary",
+            "displaySummary",
+            "order",
+          ]),
+        ],
+      },
+    },
+  });

package/src/features/handbook/HandbookThreadMessageModule.ts

@@ -0,0 +1,21 @@
+import { MessageCircleQuestionIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookThreadMessage } from "./data/HandbookThreadMessage";
+
+/**
+ * One turn of a handbook conversation. Like the thread, it has no `pageUrl` —
+ * a message is only ever read as part of its thread.
+ */
+export const HandbookThreadMessageModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "bef354f2-70e1-4f4f-9953-10d3d74cad0c",
+    name: "handbookthreadmessages",
+    model: HandbookThreadMessage,
+    icon: MessageCircleQuestionIcon,
+    inclusions: {
+      lists: {
+        fields: [createJsonApiInclusion("handbookthreadmessages", ["role", "content", "position", "sources"])],
+      },
+    },
+  });