@manablox/api-public 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@manablox/api-public",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@manablox/core": "0.1.0",
+    "@manablox/db": "0.1.0",
+    "@manablox/media": "0.1.0",
+    "@manablox/services": "0.1.0",
+    "@orpc/server": "^1.15.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@manablox/config-typescript": "0.0.0",
+    "@manablox/fields": "0.1.0",
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/context.ts

@@ -0,0 +1,22 @@
+import type { Manablox } from '@manablox/core';
+import type { Repositories } from '@manablox/db';
+import type { MediaService } from '@manablox/media';
+import type { Loaders } from '@manablox/services';
+
+/**
+ * The delivery context.
+ *
+ * Compare `RpcContext`: no `auth`, no `apiKeys`, no `principal`, no `content` service.
+ * A procedure here cannot authenticate a caller or write, because the context it runs
+ * in has nothing to do it with — the read-only guarantee is a property of the type, not
+ * a rule contributors have to remember.
+ */
+export interface PublicContext {
+  manablox: Manablox;
+  repos: Repositories;
+  media: MediaService;
+  loaders: Loaders;
+  /** The one space this instance serves. Never taken from the request. */
+  spaceId: string;
+  locale: string;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './context.js';
+export * from './router.js';
+export * from './serialize.js';

package/src/router.ts

@@ -0,0 +1,298 @@
+import { ManabloxError, resolveGraphQL } from '@manablox/core';
+import { ORPCError, os } from '@orpc/server';
+import { z } from 'zod';
+import type { PublicContext } from './context.js';
+import {
+  type PublicAsset,
+  type PublicContent,
+  parseExpand,
+  serializeAsset,
+  serializeContent,
+  serializeContents,
+} from './serialize.js';
+
+/**
+ * The base procedure.
+ *
+ * There is no `authed` and no `scoped` sibling here, and that is the point: a public
+ * procedure has no principal to check, so the only middleware is the error mapping.
+ */
+const base = os.$context<PublicContext>().use(async ({ next }) => {
+  try {
+    return await next();
+  } catch (error) {
+    if (!ManabloxError.is(error)) throw error;
+    const code = (
+      {
+        validation: 'BAD_REQUEST',
+        bad_request: 'BAD_REQUEST',
+        not_found: 'NOT_FOUND',
+        conflict: 'CONFLICT',
+        forbidden: 'FORBIDDEN',
+        unauthorized: 'UNAUTHORIZED',
+        internal: 'INTERNAL_SERVER_ERROR',
+      } as const
+    )[error.kind];
+    throw new ORPCError(code, { message: error.key, data: { key: error.key } });
+  }
+});
+
+const uuid = z.string().uuid();
+const expandArg = z
+  .string()
+  .max(200)
+  .optional()
+  .describe('Comma-separated relation fields to inline, e.g. `hero,author`.');
+
+const contentSchema: z.ZodType<PublicContent> = z.object({
+  id: z.string(),
+  type: z.string(),
+  title: z.string(),
+  slug: z.string(),
+  permalink: z.string().nullable(),
+  locale: z.string(),
+  parentId: z.string().nullable(),
+  publishedAt: z.string().nullable(),
+  updatedAt: z.string(),
+  fields: z.record(z.string(), z.unknown()),
+});
+
+const assetSchema: z.ZodType<PublicAsset> = z.object({
+  id: z.string(),
+  url: z.string(),
+  filename: z.string(),
+  mimeType: z.string(),
+  size: z.number(),
+  width: z.number().nullable(),
+  height: z.number().nullable(),
+  alt: z.string().nullable(),
+  title: z.string().nullable(),
+  variants: z.record(z.string(), z.string()),
+});
+
+const listSchema = z.object({
+  items: z.array(contentSchema),
+  total: z.number(),
+  limit: z.number(),
+  offset: z.number(),
+});
+
+/**
+ * The public delivery API: one definition yielding REST, an OpenAPI document and the
+ * SDK's types. No `spaceId` appears anywhere — the space is pinned in the context.
+ */
+export const publicRouter = {
+  list: base
+    .route({
+      method: 'GET',
+      path: '/content',
+      summary: 'List published documents',
+      tags: ['content'],
+    })
+    .input(
+      z.object({
+        type: z.string().max(100).optional(),
+        parentId: uuid.optional(),
+        under: uuid.optional(),
+        search: z.string().max(200).optional(),
+        locale: z.string().max(10).optional(),
+        limit: z.coerce.number().int().min(1).max(100).default(25),
+        offset: z.coerce.number().int().min(0).default(0),
+        expand: expandArg,
+      }),
+    )
+    .output(listSchema)
+    .handler(async ({ input, context }) => {
+      const typeIds = input.type
+        ? [context.manablox.contentTypes.getByName(input.type, context.spaceId).id]
+        : undefined;
+
+      const page = await context.repos.content.list(
+        {
+          spaceId: context.spaceId,
+          locale: input.locale ?? context.locale,
+          ...(typeIds ? { typeIds } : {}),
+          ...(input.parentId ? { parentId: input.parentId } : {}),
+          ...(input.under ? { under: input.under } : {}),
+          ...(input.search ? { search: input.search } : {}),
+        },
+        { limit: input.limit, offset: input.offset },
+        [],
+        // The published projection, always. There is no other option on this router.
+        true,
+      );
+
+      return {
+        items: await serializeContents(page.items, context, parseExpand(input.expand)),
+        total: page.total,
+        limit: page.limit,
+        offset: page.offset,
+      };
+    }),
+
+  get: base
+    .route({
+      method: 'GET',
+      path: '/content/{id}',
+      summary: 'Fetch one published document by id',
+      tags: ['content'],
+    })
+    .input(z.object({ id: uuid, expand: expandArg }))
+    .output(contentSchema)
+    .handler(async ({ input, context }) => {
+      // The loader is space-scoped, so an id from another tenant simply does not resolve.
+      const row = await context.loaders.publishedContent.load(input.id);
+      if (!row) throw ManabloxError.notFound('content.notFound', { id: input.id });
+      return serializeContent(row, context, parseExpand(input.expand));
+    }),
+
+  byPermalink: base
+    .route({
+      method: 'GET',
+      path: '/permalink/{+path}',
+      summary: 'Resolve a URL path to a document',
+      tags: ['content'],
+    })
+    .input(
+      z.object({
+        path: z.string().max(2000),
+        locale: z.string().max(10).optional(),
+        expand: expandArg,
+      }),
+    )
+    .output(contentSchema)
+    .handler(async ({ input, context }) => {
+      const permalink = input.path.replace(/^\/+|\/+$/g, '');
+      const row = await context.repos.content.findByPermalink(
+        context.spaceId,
+        input.locale ?? context.locale,
+        permalink,
+        true,
+      );
+      if (!row) throw ManabloxError.notFound('content.notFound', { permalink });
+      return serializeContent(row, context, parseExpand(input.expand));
+    }),
+
+  menu: base
+    .route({ method: 'GET', path: '/menu', summary: 'The navigation tree', tags: ['content'] })
+    .input(
+      z.object({
+        rootId: uuid.optional(),
+        locale: z.string().max(10).optional(),
+        expand: expandArg,
+      }),
+    )
+    .output(z.object({ items: z.array(contentSchema) }))
+    .handler(async ({ input, context }) => {
+      const page = await context.repos.content.list(
+        {
+          spaceId: context.spaceId,
+          locale: input.locale ?? context.locale,
+          visibleInMenu: true,
+          ...(input.rootId ? { under: input.rootId } : {}),
+        },
+        { limit: 500, offset: 0 },
+        [{ by: 'position', direction: 'asc' }],
+        true,
+      );
+      return { items: await serializeContents(page.items, context, parseExpand(input.expand)) };
+    }),
+
+  asset: base
+    .route({
+      method: 'GET',
+      path: '/assets/{id}',
+      summary: 'Fetch asset metadata',
+      tags: ['media'],
+    })
+    .input(z.object({ id: uuid }))
+    .output(assetSchema)
+    .handler(async ({ input, context }) => {
+      // Space-scoped and publication-gated by the loader the public instance builds.
+      const asset = await context.loaders.asset.load(input.id);
+      if (!asset) throw ManabloxError.notFound('asset.notFound', { id: input.id });
+      return serializeAsset(asset, context);
+    }),
+
+  types: base
+    .route({
+      method: 'GET',
+      path: '/types',
+      summary: 'The space content model, for SDK type generation',
+      tags: ['schema'],
+    })
+    .input(z.object({}).optional())
+    .output(
+      z.object({
+        types: z.array(
+          z.object({
+            name: z.string(),
+            label: z.string(),
+            kind: z.enum(['content', 'block']),
+            fields: z.array(
+              z.object({
+                name: z.string(),
+                type: z.string(),
+                required: z.boolean(),
+                list: z.boolean(),
+                /** `scalar` carries a GraphQL scalar name, `ref` a target, `block` neither. */
+                kind: z.enum(['scalar', 'ref', 'block']),
+                scalar: z.string().optional(),
+                target: z.enum(['content', 'asset', 'user']).optional(),
+                blockTypes: z.array(z.string()).optional(),
+              }),
+            ),
+          }),
+        ),
+      }),
+    )
+    .handler(({ context }) => {
+      const registry = context.manablox.contentTypes;
+
+      return {
+        types: registry.all
+          .filter((type) => type.spaceId === null || type.spaceId === context.spaceId)
+          .map((type) => ({
+            name: type.name,
+            label: type.label,
+            kind: type.kind,
+            fields: type.fields
+              // Role-gated fields are absent from every public surface, so they must be
+              // absent from the generated types too — otherwise the SDK promises a field
+              // that never arrives.
+              .filter((field) => !field.readRoles?.length)
+              .flatMap((field) => {
+                const fieldType = registry.fieldTypes.tryGet(field.type);
+                if (!fieldType) return [];
+                const spec = resolveGraphQL(fieldType, field.settings);
+                const blockTypes = blockTypeNames(context, field.settings);
+
+                return [
+                  {
+                    name: field.name,
+                    type: field.type,
+                    required: field.required ?? false,
+                    list: spec.list ?? false,
+                    kind: spec.type.kind,
+                    ...(spec.type.kind === 'scalar' ? { scalar: spec.type.name } : {}),
+                    ...(spec.type.kind === 'ref' ? { target: spec.type.target } : {}),
+                    ...(spec.type.kind === 'block' && blockTypes ? { blockTypes } : {}),
+                  },
+                ];
+              }),
+          })),
+      };
+    }),
+};
+
+export type PublicRouter = typeof publicRouter;
+
+/** A `blocks` field names its allowed types by id; the SDK needs their names. */
+function blockTypeNames(context: PublicContext, settings: unknown): string[] | undefined {
+  const types = (settings as { types?: unknown } | undefined)?.types;
+  if (!Array.isArray(types)) return undefined;
+  return types
+    .filter((id): id is string => typeof id === 'string')
+    .map((id) => context.manablox.contentTypes.tryGet(id)?.name)
+    .filter((name): name is string => Boolean(name));
+}

package/src/serialize.ts

@@ -0,0 +1,333 @@
+import {
+  type ContentTypeDefinition,
+  fieldBlocks,
+  type Manablox,
+  resolveGraphQL,
+} from '@manablox/core';
+import type { AssetRow, ContentRow, UserRow } from '@manablox/db';
+import { absoluteMediaUrl } from '@manablox/media';
+import type { PublicContext } from './context.js';
+
+export interface PublicAsset {
+  id: string;
+  url: string;
+  filename: string;
+  mimeType: string;
+  size: number;
+  width: number | null;
+  height: number | null;
+  alt: string | null;
+  title: string | null;
+  /**
+   * Signed transform URLs, keyed by preset name.
+   *
+   * The signature is an HMAC of the instance's media secret, so a client cannot mint
+   * one — an unsigned transform request is a resize amplifier and is refused. That is
+   * why the URLs are served rather than constructed in the SDK.
+   */
+  variants: Record<string, string>;
+}
+
+export interface PublicUser {
+  id: string;
+  name: string;
+  image: string | null;
+}
+
+export interface PublicContent {
+  id: string;
+  type: string;
+  title: string;
+  slug: string;
+  permalink: string | null;
+  locale: string;
+  parentId: string | null;
+  publishedAt: string | null;
+  updatedAt: string;
+  /**
+   * A plain map keyed by field name — `{ title, summary, components: [...] }`.
+   *
+   * GraphQL's per-type object is richer; REST's job is to be pleasant to consume with
+   * no schema knowledge, which a keyed map is and a tagged union is not.
+   */
+  fields: Record<string, unknown>;
+}
+
+export interface PublicBlock {
+  blockId: string;
+  type: string;
+  fields: Record<string, unknown>;
+}
+
+/** Which relation fields to inline rather than leave as ids. */
+export type ExpandSet = ReadonlySet<string>;
+
+export function parseExpand(raw: string | undefined): ExpandSet {
+  if (!raw) return new Set();
+  return new Set(
+    raw
+      .split(',')
+      .map((name) => name.trim())
+      .filter(Boolean),
+  );
+}
+
+interface Collected {
+  content: Set<string>;
+  asset: Set<string>;
+  user: Set<string>;
+}
+
+interface Resolved {
+  content: Map<string, ContentRow>;
+  asset: Map<string, AssetRow>;
+  user: Map<string, UserRow>;
+}
+
+/**
+ * Serialises rows for the REST surface.
+ *
+ * Three passes, not one: collect every id the expansion will need, load each target in
+ * a single batch, then build the output synchronously. Serialising and loading in one
+ * pass would still be correct — DataLoader batches within a tick — but it would depend
+ * on nothing in the walk ever awaiting, which is exactly the kind of invariant that
+ * quietly breaks and reintroduces the N+1 this whole layer exists to avoid.
+ */
+export async function serializeContents(
+  rows: ContentRow[],
+  ctx: PublicContext,
+  expand: ExpandSet,
+): Promise<PublicContent[]> {
+  const collected: Collected = { content: new Set(), asset: new Set(), user: new Set() };
+  for (const row of rows) collectRow(row, ctx.manablox, expand, collected);
+
+  const resolved = await resolveAll(collected, ctx);
+  return rows.map((row) => buildContent(row, ctx, expand, resolved));
+}
+
+export async function serializeContent(
+  row: ContentRow,
+  ctx: PublicContext,
+  expand: ExpandSet,
+): Promise<PublicContent> {
+  const [only] = await serializeContents([row], ctx, expand);
+  // `serializeContents` maps one-to-one, so this is total; the assertion documents it.
+  return only as PublicContent;
+}
+
+export function serializeAsset(asset: AssetRow, ctx: PublicContext): PublicAsset {
+  // Absolute: a delivery consumer is on its own origin, and a root-relative `/media/…`
+  // would resolve against the *frontend* rather than the API.
+  const base = ctx.manablox.config.server.publicUrl;
+
+  return {
+    id: asset.id,
+    url: absoluteMediaUrl(ctx.media.urlFor(asset), base),
+    variants: buildVariants(asset, ctx),
+    filename: asset.filename,
+    mimeType: asset.mimeType,
+    size: asset.size,
+    width: asset.width,
+    height: asset.height,
+    alt: asset.alt,
+    title: asset.title,
+  };
+}
+
+/** Each configured preset, at the format the preset itself declares. */
+function buildVariants(asset: AssetRow, ctx: PublicContext): Record<string, string> {
+  if (!asset.mimeType.startsWith('image/')) return {};
+
+  const presets = ctx.manablox.config.media.presets;
+  const base = ctx.manablox.config.server.publicUrl;
+
+  const out: Record<string, string> = {};
+  for (const [name, preset] of Object.entries(presets)) {
+    out[name] = absoluteMediaUrl(ctx.media.urlFor(asset, name, preset.format ?? 'webp'), base);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Pass 1 — collect
+// ---------------------------------------------------------------------------
+
+function collectRow(row: ContentRow, manablox: Manablox, expand: ExpandSet, into: Collected): void {
+  const type = manablox.contentTypes.tryGet(row.typeId);
+  if (!type) return;
+  collectFields(type, row.fields, manablox, expand, into, 0);
+}
+
+function collectFields(
+  type: ContentTypeDefinition,
+  values: Record<string, unknown>,
+  manablox: Manablox,
+  expand: ExpandSet,
+  into: Collected,
+  depth: number,
+): void {
+  if (depth > 16) return;
+
+  for (const field of type.fields) {
+    if (field.readRoles?.length) continue;
+    const fieldType = manablox.fieldTypes.tryGet(field.type);
+    if (!fieldType) continue;
+
+    const value = values[field.name];
+    const spec = resolveGraphQL(fieldType, field.settings);
+
+    if (spec.type.kind === 'ref' && expand.has(field.name)) {
+      for (const id of toIds(value)) into[spec.type.target].add(id);
+    }
+
+    if (fieldType.nested) {
+      for (const block of fieldBlocks(fieldType, value, field.settings)) {
+        const blockType = manablox.contentTypes.tryGet(block.type);
+        if (blockType) {
+          collectFields(blockType, block.fields, manablox, expand, into, depth + 1);
+        }
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pass 2 — load
+// ---------------------------------------------------------------------------
+
+async function resolveAll(collected: Collected, ctx: PublicContext): Promise<Resolved> {
+  const [contents, assets, users] = await Promise.all([
+    loadMany(ctx.loaders.publishedContent, collected.content),
+    loadMany(ctx.loaders.asset, collected.asset),
+    loadMany(ctx.loaders.user, collected.user),
+  ]);
+
+  return { content: contents, asset: assets, user: users };
+}
+
+async function loadMany<T extends { id: string }>(
+  loader: { loadMany: (ids: string[]) => Promise<Array<T | null | Error>> },
+  ids: Set<string>,
+): Promise<Map<string, T>> {
+  if (ids.size === 0) return new Map();
+  const rows = await loader.loadMany([...ids]);
+  const map = new Map<string, T>();
+  for (const row of rows) {
+    if (row && !(row instanceof Error)) map.set(row.id, row);
+  }
+  return map;
+}
+
+// ---------------------------------------------------------------------------
+// Pass 3 — build
+// ---------------------------------------------------------------------------
+
+function buildContent(
+  row: ContentRow,
+  ctx: PublicContext,
+  expand: ExpandSet,
+  resolved: Resolved,
+): PublicContent {
+  const type = ctx.manablox.contentTypes.tryGet(row.typeId);
+  return {
+    id: row.id,
+    type: type?.name ?? 'unknown',
+    title: row.title,
+    slug: row.slug,
+    permalink: row.permalink,
+    locale: row.locale,
+    parentId: row.parentId,
+    publishedAt: row.publishedAt ? row.publishedAt.toISOString() : null,
+    updatedAt: row.updatedAt.toISOString(),
+    fields: type ? buildFields(type, row.fields, ctx, expand, resolved, 0) : {},
+  };
+}
+
+function buildFields(
+  type: ContentTypeDefinition,
+  values: Record<string, unknown>,
+  ctx: PublicContext,
+  expand: ExpandSet,
+  resolved: Resolved,
+  depth: number,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (depth > 16) return out;
+
+  for (const field of type.fields) {
+    // Role-gated fields are omitted entirely, exactly as in the GraphQL schema — a
+    // surface that returned them would make the two views disagree.
+    if (field.readRoles?.length) continue;
+
+    const fieldType = ctx.manablox.fieldTypes.tryGet(field.type);
+    if (!fieldType) continue;
+
+    const value = values[field.name];
+    const spec = resolveGraphQL(fieldType, field.settings);
+
+    if (fieldType.nested) {
+      const blocks = fieldBlocks(fieldType, value, field.settings).map((block) => {
+        const blockType = ctx.manablox.contentTypes.tryGet(block.type);
+        return {
+          blockId: block.blockId,
+          type: blockType?.name ?? 'unknown',
+          fields: blockType
+            ? buildFields(blockType, block.fields, ctx, expand, resolved, depth + 1)
+            : {},
+        } satisfies PublicBlock;
+      });
+      out[field.name] = spec.list === false ? (blocks[0] ?? null) : blocks;
+      continue;
+    }
+
+    if (spec.type.kind === 'ref' && expand.has(field.name)) {
+      const ids = toIds(value);
+      const inlined = ids
+        .map((id) =>
+          inline(spec.type.kind === 'ref' ? spec.type.target : 'content', id, ctx, resolved),
+        )
+        .filter((entry) => entry !== null);
+      out[field.name] = spec.list ? inlined : (inlined[0] ?? null);
+      continue;
+    }
+
+    out[field.name] = value ?? null;
+  }
+
+  return out;
+}
+
+function inline(
+  target: 'content' | 'asset' | 'user',
+  id: string,
+  ctx: PublicContext,
+  resolved: Resolved,
+): unknown {
+  if (target === 'asset') {
+    const asset = resolved.asset.get(id);
+    return asset ? serializeAsset(asset, ctx) : null;
+  }
+  if (target === 'user') {
+    const user = resolved.user.get(id);
+    return user ? ({ id: user.id, name: user.name, image: user.image } satisfies PublicUser) : null;
+  }
+
+  const row = resolved.content.get(id);
+  if (!row) return null;
+  // A one-level summary, not a recursive expansion: `?expand=` inlining its own
+  // relations is how a cheap parameter becomes an unbounded traversal.
+  return {
+    id: row.id,
+    type: ctx.manablox.contentTypes.tryGet(row.typeId)?.name ?? 'unknown',
+    title: row.title,
+    permalink: row.permalink,
+    locale: row.locale,
+  };
+}
+
+function toIds(value: unknown): string[] {
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value))
+    return value.filter((entry): entry is string => typeof entry === 'string');
+  return [];
+}

package/test/serialize.test.ts

@@ -0,0 +1,177 @@
+import { Manablox } from '@manablox/core';
+import { builtinFieldTypes } from '@manablox/fields';
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { PublicContext } from '../src/context.js';
+import { parseExpand, serializeContents } from '../src/serialize.js';
+
+const SPACE = '11111111-1111-4111-8111-111111111111';
+const ASSET = '22222222-2222-4222-8222-222222222222';
+const RELATED = '33333333-3333-4333-8333-333333333333';
+
+let manablox: Manablox;
+let loads: string[];
+
+beforeAll(async () => {
+  manablox = new Manablox({
+    database: { url: 'postgres://unused' },
+    auth: { secret: 'test' },
+    fieldTypes: builtinFieldTypes,
+    logLevel: 'silent',
+    contentTypes: [
+      {
+        name: 'teaser',
+        kind: 'block',
+        fields: [
+          { name: 'headline', type: 'string' },
+          { name: 'image', type: 'asset' },
+        ],
+      },
+      {
+        name: 'page',
+        fields: [
+          { name: 'summary', type: 'string' },
+          { name: 'hero', type: 'asset' },
+          { name: 'related', type: 'content', settings: { multiple: true, types: [] } },
+          { name: 'secret', type: 'string', readRoles: ['admin'] },
+        ],
+      },
+    ],
+  });
+  await manablox.init();
+});
+
+const asset = (id: string) => ({
+  id,
+  spaceId: SPACE,
+  filename: 'x.jpg',
+  name: 'x',
+  mimeType: 'image/jpeg',
+  size: 1,
+  width: 10,
+  height: 10,
+  alt: 'alt',
+  title: null,
+});
+
+function context(): PublicContext {
+  loads = [];
+  const loader = <T>(build: (id: string) => T | null, label: string) => ({
+    load: async (id: string) => {
+      loads.push(`${label}:1`);
+      return build(id);
+    },
+    loadMany: async (ids: string[]) => {
+      // One entry per *batch*, so the test can assert batching rather than call count.
+      loads.push(`${label}:${ids.length}`);
+      return ids.map(build);
+    },
+  });
+
+  return {
+    manablox,
+    repos: {} as never,
+    media: { urlFor: (row: { id: string }) => `https://cdn.test/${row.id}` } as never,
+    loaders: {
+      asset: loader((id) => asset(id), 'asset'),
+      user: loader(() => null, 'user'),
+      publishedContent: loader(
+        (id) => ({
+          id,
+          typeId: manablox.contentTypes.getByName('page').id,
+          title: 'Related',
+          permalink: 'related',
+          locale: 'en',
+        }),
+        'content',
+      ),
+      content: loader(() => null, 'draft'),
+      children: loader(() => [], 'children'),
+    } as never,
+    spaceId: SPACE,
+    locale: 'en',
+  };
+}
+
+const row = (over: Record<string, unknown> = {}) =>
+  ({
+    id: 'c1',
+    spaceId: SPACE,
+    typeId: manablox.contentTypes.getByName('page').id,
+    title: 'A page',
+    slug: 'a-page',
+    permalink: 'a-page',
+    locale: 'en',
+    parentId: null,
+    publishedAt: new Date('2026-01-01T00:00:00Z'),
+    updatedAt: new Date('2026-01-02T00:00:00Z'),
+    fields: { summary: 'hello', hero: ASSET, related: [RELATED], secret: 'nope' },
+    ...over,
+  }) as never;
+
+describe('serializer', () => {
+  it('returns fields as a plain map keyed by field name', async () => {
+    const [result] = await serializeContents([row()], context(), parseExpand(undefined));
+    expect(result?.fields).toEqual({ summary: 'hello', hero: ASSET, related: [RELATED] });
+    expect(result?.type).toBe('page');
+    expect(result?.publishedAt).toBe('2026-01-01T00:00:00.000Z');
+  });
+
+  it('omits role-gated fields', async () => {
+    const [result] = await serializeContents([row()], context(), parseExpand(undefined));
+    expect(result?.fields).not.toHaveProperty('secret');
+  });
+
+  it('inlines only the relations named in expand', async () => {
+    const [result] = await serializeContents([row()], context(), parseExpand('hero'));
+    expect(result?.fields.hero).toMatchObject({ id: ASSET, url: `https://cdn.test/${ASSET}` });
+    // `related` was not requested, so it stays a list of ids.
+    expect(result?.fields.related).toEqual([RELATED]);
+  });
+
+  it('loads each relation target in one batch however many rows there are', async () => {
+    const rows = Array.from({ length: 50 }, (_, i) => row({ id: `c${i}` }));
+    await serializeContents(rows, context(), parseExpand('hero,related'));
+
+    // One asset batch and one content batch — not fifty of each.
+    expect(loads.filter((entry) => entry.startsWith('asset:'))).toEqual(['asset:1']);
+    expect(loads.filter((entry) => entry.startsWith('content:'))).toEqual(['content:1']);
+  });
+
+  it('walks into blocks', async () => {
+    const teaser = manablox.contentTypes.getByName('teaser');
+    const withBlocks = row({
+      typeId: manablox.contentTypes.getByName('page').id,
+      fields: {
+        summary: 's',
+        hero: null,
+        related: [],
+        blocks: [{ blockId: 'b1', type: teaser.id, fields: { headline: 'Hi', image: ASSET } }],
+      },
+    });
+
+    // `page` has no blocks field, so nothing should appear — the walker must not invent
+    // fields the content type does not declare.
+    const [result] = await serializeContents([withBlocks], context(), parseExpand(undefined));
+    expect(result?.fields).not.toHaveProperty('blocks');
+  });
+
+  it('inlines a content relation as a summary, not a recursive expansion', async () => {
+    const [result] = await serializeContents([row()], context(), parseExpand('related'));
+    const [related] = result?.fields.related as Array<Record<string, unknown>>;
+    expect(related).toEqual({
+      id: RELATED,
+      type: 'page',
+      title: 'Related',
+      permalink: 'related',
+      locale: 'en',
+    });
+    expect(related).not.toHaveProperty('fields');
+  });
+});
+
+describe('parseExpand', () => {
+  it('accepts a comma list and ignores blanks', () => {
+    expect([...parseExpand('hero, author,,')]).toEqual(['hero', 'author']);
+    expect(parseExpand(undefined).size).toBe(0);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "@manablox/config-typescript/library.json", "include": ["src", "test"] }

package/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: { environment: 'node', include: ['test/**/*.test.ts'] },
+});