@manablox/api-public 0.2.0 → 0.4.0

package/src/index.ts

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

package/src/router.ts

@@ -1,365 +0,0 @@
-import { ManabloxError, resolveGraphQL, TRANSPORT_CODE } from '@manablox/core';
-import type { ContentRow } from '@manablox/db';
-import { type PublicMenuItem, toPublicListQuery } from '@manablox/services';
-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;
-    throw new ORPCError(TRANSPORT_CODE[error.kind], {
-      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(),
-  focalPoint: z.object({ x: z.number(), y: z.number() }).nullable(),
-  crop: z
-    .object({ left: z.number(), top: z.number(), width: z.number(), height: z.number() })
-    .nullable(),
-  variants: z.record(z.string(), z.string()),
-});
-
-/** A menu entry for REST: the document inlined, sub-entries nested. */
-interface PublicMenuEntry {
-  id: string;
-  label: string;
-  url: string | null;
-  content: PublicContent | null;
-  children: PublicMenuEntry[];
-}
-
-const menuItemSchema: z.ZodType<PublicMenuEntry> = z.lazy(() =>
-  z.object({
-    id: z.string(),
-    label: z.string(),
-    url: z.string().nullable(),
-    content: contentSchema.nullable(),
-    children: z.array(menuItemSchema),
-  }),
-);
-
-const menuSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  machineName: z.string(),
-  items: z.array(menuItemSchema),
-});
-
-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 query = toPublicListQuery(context.manablox.contentTypes, input, {
-        spaceId: context.spaceId,
-        locale: context.locale,
-      });
-      // The published projection, always. There is no other option on this router.
-      const page = await context.repos.content.list(
-        query.filter,
-        query.pagination,
-        query.sorts,
-        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(({ input, context }) => resolvePermalink(input.path, input, context)),
-
-  // `{+path}` needs at least one character, so the empty path — the space's home page,
-  // which the repository resolves through `settings.homeContentId` — gets a route of
-  // its own. The SDK calls it for `byPermalink('/')`.
-  home: base
-    .route({
-      method: 'GET',
-      path: '/permalink',
-      summary: "Resolve the space's home page",
-      tags: ['content'],
-    })
-    .input(z.object({ locale: z.string().max(10).optional(), expand: expandArg }))
-    .output(contentSchema)
-    .handler(({ input, context }) => resolvePermalink('', input, context)),
-
-  menu: base
-    .route({
-      method: 'GET',
-      path: '/menus/{name}',
-      summary: 'A navigation menu by name',
-      tags: ['content'],
-    })
-    .input(
-      z.object({
-        name: z
-          .string()
-          .regex(/^[a-z][a-z0-9_-]*$/)
-          .max(64),
-        locale: z.string().max(10).optional(),
-        expand: expandArg,
-      }),
-    )
-    .output(menuSchema)
-    .handler(async ({ input, context }) => {
-      const menu = await context.menus.resolve(
-        context.spaceId,
-        input.name,
-        input.locale ?? context.locale,
-        true,
-      );
-      if (!menu) throw ManabloxError.notFound('menu.notFound', { id: input.name });
-
-      // One batch for every document in the tree, then the tree is rebuilt around them.
-      const rows = collectMenuRows(menu.items);
-      const serialised = await serializeContents(rows, context, parseExpand(input.expand));
-      const byId = new Map(rows.map((row, index) => [row.id, serialised[index] as PublicContent]));
-      const toEntry = (item: PublicMenuItem): PublicMenuEntry => ({
-        id: item.id,
-        label: item.label,
-        url: item.url,
-        content: item.content ? (byId.get(item.content.id) ?? null) : null,
-        children: item.children.map(toEntry),
-      });
-      return {
-        id: menu.id,
-        name: menu.name,
-        machineName: menu.machineName,
-        items: menu.items.map(toEntry),
-      };
-    }),
-
-  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));
-}
-
-function collectMenuRows(items: PublicMenuItem[]): ContentRow[] {
-  const out: ContentRow[] = [];
-  for (const item of items) {
-    if (item.content) out.push(item.content);
-    out.push(...collectMenuRows(item.children));
-  }
-  return out;
-}
-
-async function resolvePermalink(
-  path: string,
-  input: { locale?: string | undefined; expand?: string | undefined },
-  context: PublicContext,
-): Promise<PublicContent> {
-  const permalink = 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));
-}

package/src/serialize.ts

@@ -1,346 +0,0 @@
-import {
-  type AssetCrop,
-  type ContentTypeDefinition,
-  type FocalPoint,
-  fieldBlocks,
-  type Manablox,
-  resolveGraphQL,
-} from '@manablox/core';
-import type { AssetRow, ContentRow, UserRow } from '@manablox/db';
-import { absoluteMediaUrl, readImageEdits } 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;
-  /**
-   * Where the subject is, as fractions of the (cropped) image, or `null` for centred.
-   * Variants already honour it; it is here for a frontend that renders the original
-   * itself, e.g. as CSS `object-position`.
-   */
-  focalPoint: FocalPoint | null;
-  /** The editor's crop in the original's pixels, or `null`. Variants are cut to it. */
-  crop: AssetCrop | 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;
-  const edits = readImageEdits(asset.meta);
-
-  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,
-    focalPoint: edits.focalPoint ?? null,
-    crop: edits.crop ?? null,
-  };
-}
-
-/** 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 [];
-}