@manablox/api-public 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,19 @@
+# `@manablox/api-public`
+
+The delivery REST API under `/v1`: an oRPC router with no principal in its context — the read-only guarantee is a property of the type — plus the serialiser that inlines relations on `expand` and the `/types` endpoint the SDK generates types from.
+
+## Exports
+
+- `publicRouter` / `PublicRouter`
+- `PublicContext`
+- `serializeContent`, `serializeContents`, `serializeAsset`, `parseExpand`
+
+## Depends on
+
+@manablox/services, @orpc/server, zod
+
+## Test
+
+```sh
+pnpm --filter @manablox/api-public test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manablox/api-public",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -11,16 +11,16 @@
   "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",
+    "@manablox/core": "0.2.0",
+    "@manablox/db": "0.2.0",
+    "@manablox/media": "0.2.0",
+    "@manablox/services": "0.2.0",
     "@orpc/server": "^1.15.0",
     "zod": "^4.5.4"
   },
   "devDependencies": {
     "@manablox/config-typescript": "0.0.0",
-    "@manablox/fields": "0.1.0",
+    "@manablox/fields": "0.2.0",
     "@types/node": "^26.4.1",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"

package/src/context.ts

@@ -1,7 +1,7 @@
 import type { Manablox } from '@manablox/core';
 import type { Repositories } from '@manablox/db';
 import type { MediaService } from '@manablox/media';
-import type { Loaders } from '@manablox/services';
+import type { Loaders, MenuService } from '@manablox/services';
 
 /**
  * The delivery context.
@@ -15,6 +15,7 @@ export interface PublicContext {
   manablox: Manablox;
   repos: Repositories;
   media: MediaService;
+  menus: MenuService;
   loaders: Loaders;
   /** The one space this instance serves. Never taken from the request. */
   spaceId: string;

package/src/router.ts

@@ -1,4 +1,6 @@
-import { ManabloxError, resolveGraphQL } from '@manablox/core';
+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';
@@ -22,18 +24,10 @@ const base = os.$context<PublicContext>().use(async ({ next }) => {
     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 } });
+    throw new ORPCError(TRANSPORT_CODE[error.kind], {
+      message: error.key,
+      data: { key: error.key },
+    });
   }
 });
 
@@ -67,9 +61,39 @@ const assetSchema: z.ZodType<PublicAsset> = z.object({
   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(),
@@ -103,22 +127,15 @@ export const publicRouter = {
     )
     .output(listSchema)
     .handler(async ({ input, context }) => {
-      const typeIds = input.type
-        ? [context.manablox.contentTypes.getByName(input.type, context.spaceId).id]
-        : undefined;
-
+      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(
-        {
-          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.
+        query.filter,
+        query.pagination,
+        query.sorts,
         true,
       );
 
@@ -161,41 +178,66 @@ export const publicRouter = {
       }),
     )
     .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));
-    }),
+    .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: '/menu', summary: 'The navigation tree', tags: ['content'] })
+    .route({
+      method: 'GET',
+      path: '/menus/{name}',
+      summary: 'A navigation menu by name',
+      tags: ['content'],
+    })
     .input(
       z.object({
-        rootId: uuid.optional(),
+        name: z
+          .string()
+          .regex(/^[a-z][a-z0-9_-]*$/)
+          .max(64),
         locale: z.string().max(10).optional(),
         expand: expandArg,
       }),
     )
-    .output(z.object({ items: z.array(contentSchema) }))
+    .output(menuSchema)
     .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' }],
+      const menu = await context.menus.resolve(
+        context.spaceId,
+        input.name,
+        input.locale ?? context.locale,
         true,
       );
-      return { items: await serializeContents(page.items, context, parseExpand(input.expand)) };
+      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
@@ -296,3 +338,28 @@ function blockTypeNames(context: PublicContext, settings: unknown): string[] | u
     .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,11 +1,13 @@
 import {
+  type AssetCrop,
   type ContentTypeDefinition,
+  type FocalPoint,
   fieldBlocks,
   type Manablox,
   resolveGraphQL,
 } from '@manablox/core';
 import type { AssetRow, ContentRow, UserRow } from '@manablox/db';
-import { absoluteMediaUrl } from '@manablox/media';
+import { absoluteMediaUrl, readImageEdits } from '@manablox/media';
 import type { PublicContext } from './context.js';
 
 export interface PublicAsset {
@@ -18,6 +20,14 @@ export interface PublicAsset {
   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.
    *
@@ -119,6 +129,7 @@ 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,
@@ -131,6 +142,8 @@ export function serializeAsset(asset: AssetRow, ctx: PublicContext): PublicAsset
     height: asset.height,
     alt: asset.alt,
     title: asset.title,
+    focalPoint: edits.focalPoint ?? null,
+    crop: edits.crop ?? null,
   };
 }
 

package/test/serialize.test.ts

@@ -70,6 +70,7 @@ function context(): PublicContext {
   return {
     manablox,
     repos: {} as never,
+    menus: {} as never,
     media: { urlFor: (row: { id: string }) => `https://cdn.test/${row.id}` } as never,
     loaders: {
       asset: loader((id) => asset(id), 'asset'),