@manablox/api-rpc 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,20 @@
+# `@manablox/api-rpc`
+
+The management API as an oRPC router: input schemas, permission middleware and one service call per procedure. The admin imports `ManabloxRouter` as a type and gets an end-to-end typed client with no code generation; `apps/api` also serves the same router as REST with an OpenAPI document.
+
+## Exports
+
+- `router` / `ManabloxRouter`
+- `base`, `authed`, `scoped(permission)`, `superadmin` — the procedure builders
+- `RpcContext`, `RpcRuntime`, `pickRpcRuntime`
+- `schemas` — `uuid`, `locale`, `machineName`, `pagination()`, …
+
+## Depends on
+
+@manablox/services, @manablox/auth, @orpc/server, zod
+
+## Test
+
+```sh
+pnpm --filter @manablox/api-rpc test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manablox/api-rpc",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -11,11 +11,12 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
-    "@manablox/auth": "0.1.0",
-    "@manablox/core": "0.1.0",
-    "@manablox/db": "0.1.0",
-    "@manablox/media": "0.1.0",
-    "@manablox/services": "0.1.0",
+    "@manablox/auth": "0.2.0",
+    "@manablox/core": "0.2.0",
+    "@manablox/db": "0.2.0",
+    "@manablox/media": "0.2.0",
+    "@manablox/services": "0.2.0",
+    "@manablox/workflows": "0.2.0",
     "@orpc/server": "^1.15.0",
     "@orpc/openapi": "^1.15.0",
     "zod": "^4.5.4"
@@ -27,6 +28,7 @@
     "vitest": "^5.0.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/src/base.ts

@@ -1,5 +1,5 @@
 import { assertCan, type Permission } from '@manablox/auth';
-import { ManabloxError } from '@manablox/core';
+import { ManabloxError, TRANSPORT_CODE } from '@manablox/core';
 import { ORPCError, os } from '@orpc/server';
 import type { RpcContext } from './context.js';
 
@@ -18,19 +18,7 @@ export const base = os.$context<RpcContext>().use(async ({ next }) => {
 export function toOrpcError(error: unknown): unknown {
   if (!ManabloxError.is(error)) return 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];
-
-  return new ORPCError(code, {
+  return new ORPCError(TRANSPORT_CODE[error.kind], {
     message: error.key,
     // Structured details survive to the client: key, path and params per problem.
     data: { key: error.key, details: error.details },
@@ -51,7 +39,10 @@ export const authed = base.use(async ({ context, next }) => {
  */
 export function scoped(permission: Permission) {
   return authed.use(async ({ context, next }, input: unknown) => {
-    const spaceId = (input as { spaceId?: string } | undefined)?.spaceId ?? null;
+    // The middleware sees the input before the schema runs, so a procedure whose space
+    // sits inside a `filter` object (the listings) is read there too.
+    const raw = input as { spaceId?: string; filter?: { spaceId?: string } } | undefined;
+    const spaceId = raw?.spaceId ?? raw?.filter?.spaceId ?? null;
     assertCan(context.principal, spaceId, permission);
     return next();
   });

package/src/context.ts

@@ -1,10 +1,22 @@
-import type { ApiKeyService, ManabloxAuth, Principal } from '@manablox/auth';
+import type { ApiKeyService, ManabloxAuth, Principal, UserService } from '@manablox/auth';
 import type { Manablox } from '@manablox/core';
 import type { Repositories } from '@manablox/db';
 import type { MediaService } from '@manablox/media';
-import type { ContentService, ContentTypeService, Loaders } from '@manablox/services';
+import type {
+  ContentService,
+  ContentTypeService,
+  Loaders,
+  MenuService,
+  RoleService,
+  SpaceService,
+} from '@manablox/services';
+import type { WorkflowService } from '@manablox/workflows';
 
-export interface RpcContext {
+/**
+ * The part of the host's runtime the management procedures reach for. The host's own
+ * `Runtime` extends this, so adding a service there and here is the whole change.
+ */
+export interface RpcRuntime {
   manablox: Manablox;
   repos: Repositories;
   auth: ManabloxAuth;
@@ -12,6 +24,46 @@ export interface RpcContext {
   media: MediaService;
   content: ContentService;
   contentTypes: ContentTypeService;
+  spaces: SpaceService;
+  users: UserService;
+  menus: MenuService;
+  roles: RoleService;
+  workflows: WorkflowService;
+}
+
+/** The runtime's RPC-facing slice, without whatever else the host keeps on it. */
+export function pickRpcRuntime(runtime: RpcRuntime): RpcRuntime {
+  const {
+    manablox,
+    repos,
+    auth,
+    apiKeys,
+    media,
+    content,
+    contentTypes,
+    spaces,
+    users,
+    menus,
+    roles,
+    workflows,
+  } = runtime;
+  return {
+    manablox,
+    repos,
+    auth,
+    apiKeys,
+    media,
+    content,
+    contentTypes,
+    spaces,
+    users,
+    menus,
+    roles,
+    workflows,
+  };
+}
+
+export interface RpcContext extends RpcRuntime {
   loaders: Loaders;
   principal: Principal | null;
   headers: Headers;

package/src/index.ts

@@ -1,8 +1,11 @@
 import { assetRouter } from './routers/asset.js';
 import { contentRouter } from './routers/content.js';
 import { contentTypeRouter } from './routers/content-type.js';
+import { menuRouter } from './routers/menu.js';
+import { roleRouter } from './routers/role.js';
 import { spaceRouter } from './routers/space.js';
 import { userRouter } from './routers/user.js';
+import { workflowRouter } from './routers/workflow.js';
 
 export * from './base.js';
 export * from './context.js';
@@ -17,6 +20,9 @@ export const router = {
   spaces: spaceRouter,
   assets: assetRouter,
   users: userRouter,
+  menus: menuRouter,
+  roles: roleRouter,
+  workflows: workflowRouter,
 };
 
 export type ManabloxRouter = typeof router;

package/src/routers/asset.ts

@@ -1,17 +1,27 @@
 import { z } from 'zod';
 import { scoped } from '../base.js';
+import { pagination, searchTerm, uuid } from '../schemas.js';
 
-const uuid = z.string().uuid();
+const crop = z.object({
+  left: z.number().int().min(0),
+  top: z.number().int().min(0),
+  width: z.number().int().min(1),
+  height: z.number().int().min(1),
+});
+const focalPoint = z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) });
 
 export const assetRouter = {
+  /** What an upload into this space is held to, and the instance's ceiling above it. */
+  limits: scoped('asset:read')
+    .input(z.object({ spaceId: uuid }))
+    .handler(async ({ input, context }) => context.media.limits(input.spaceId)),
+
   list: scoped('asset:read')
     .input(
-      z.object({
+      pagination({ limit: 40, max: 100 }).extend({
         spaceId: uuid,
         mimeType: z.string().optional(),
-        search: z.string().max(200).optional(),
-        limit: z.number().int().min(1).max(100).default(40),
-        offset: z.number().int().min(0).default(0),
+        search: searchTerm.optional(),
       }),
     )
     .handler(async ({ input, context }) => {
@@ -23,24 +33,22 @@ export const assetRouter = {
         },
         { limit: input.limit, offset: input.offset },
       );
-      return {
-        ...page,
-        items: page.items.map((asset) => ({
-          ...asset,
-          url: context.media.urlFor(asset),
-          thumbnailUrl: asset.mimeType.startsWith('image/')
-            ? context.media.urlFor(asset, 'thumb', 'webp')
-            : null,
-        })),
-      };
+      return { ...page, items: page.items.map((asset) => context.media.present(asset)) };
+    }),
+
+  /** Several assets in one round trip, for a field that references them; missing ids are absent. */
+  getMany: scoped('asset:read')
+    .input(z.object({ spaceId: uuid, ids: z.array(uuid).max(200) }))
+    .handler(async ({ input, context }) => {
+      const rows = await context.repos.assets.findManyByIds(input.ids, input.spaceId);
+      return rows.map((asset) => context.media.present(asset));
     }),
 
   get: scoped('asset:read')
     .input(z.object({ spaceId: uuid, id: uuid }))
     .handler(async ({ input, context }) => {
       const asset = await context.repos.assets.findById(input.id);
-      if (!asset) return null;
-      return { ...asset, url: context.media.urlFor(asset) };
+      return asset ? context.media.present(asset) : null;
     }),
 
   update: scoped('asset:write')
@@ -58,6 +66,27 @@ export const assetRouter = {
       return context.repos.assets.update(id, data);
     }),
 
+  /**
+   * An image's crop and focal point. `null` clears one; omitting it also clears it, so
+   * the call always states the whole edit. Every variant re-renders through the result.
+   */
+  setImageEdits: scoped('asset:write')
+    .input(
+      z.object({
+        spaceId: uuid,
+        id: uuid,
+        crop: crop.nullable().optional(),
+        focalPoint: focalPoint.nullable().optional(),
+      }),
+    )
+    .handler(async ({ input, context }) => {
+      const asset = await context.media.setImageEdits(input.id, {
+        crop: input.crop ?? null,
+        focalPoint: input.focalPoint ?? null,
+      });
+      return context.media.present(asset);
+    }),
+
   delete: scoped('asset:delete')
     .input(z.object({ spaceId: uuid, id: uuid }))
     .handler(async ({ input, context }) => {

package/src/routers/content-type.ts

@@ -1,8 +1,7 @@
 import { renderContentTypeConfig } from '@manablox/services';
 import { z } from 'zod';
 import { base, scoped, superadmin } from '../base.js';
-
-const uuid = z.string().uuid();
+import { uuid } from '../schemas.js';
 
 const fieldSchema = z.object({
   id: z.string().optional(),
@@ -51,7 +50,9 @@ export const contentTypeRouter = {
 
   create: scoped('contentType:write')
     .input(contentTypeSchema.extend({ spaceId: uuid }))
-    .handler(async ({ input, context }) => context.contentTypes.create(input)),
+    .handler(async ({ input, context }) =>
+      context.contentTypes.create(input, context.principal.userId),
+    ),
 
   update: scoped('contentType:write')
     .input(contentTypeSchema.extend({ spaceId: uuid, id: uuid }))

package/src/routers/content.ts

@@ -1,18 +1,20 @@
-import { actorRoles } from '@manablox/auth';
+import { actorRoles, allowedTypeIds, assertCan, type ContentPermission } from '@manablox/auth';
+import { ManabloxError } from '@manablox/core';
 import { z } from 'zod';
-import { base, scoped } from '../base.js';
-
-const uuid = z.string().uuid();
+import { base, scoped, toOrpcError } from '../base.js';
+import type { RpcContext } from '../context.js';
+import { locale, pagination, searchTerm, uuid } from '../schemas.js';
 
 const filterSchema = z.object({
   spaceId: uuid,
+  /** Specific documents, for a relation field's chips: one request instead of one per id. */
+  ids: z.array(uuid).max(200).optional(),
   typeIds: z.array(uuid).optional(),
-  locale: z.string().optional(),
+  locale: locale.optional(),
   status: z.enum(['draft', 'published', 'archived']).optional(),
   parentId: uuid.nullable().optional(),
   under: uuid.optional(),
-  search: z.string().max(200).optional(),
-  visibleInMenu: z.boolean().optional(),
+  search: searchTerm.optional(),
   fields: z
     .array(
       z.object({
@@ -39,10 +41,7 @@ const filterSchema = z.object({
     .optional(),
 });
 
-const paginationSchema = z.object({
-  limit: z.number().int().min(1).max(200).default(25),
-  offset: z.number().int().min(0).default(0),
-});
+const paginationSchema = pagination({ limit: 25, max: 200 });
 
 const sortSchema = z
   .array(
@@ -56,13 +55,12 @@ const sortSchema = z
 const saveSchema = z.object({
   spaceId: uuid,
   typeId: uuid,
-  locale: z.string().min(2).max(10).default('en'),
+  locale: locale.default('en'),
   localizationId: uuid.optional(),
   parentId: uuid.nullable().optional(),
   title: z.string().min(1).max(500),
   slug: z.string().max(200).optional(),
   fields: z.record(z.string(), z.unknown()).default({}),
-  visibleInMenu: z.boolean().optional(),
   position: z.number().int().optional(),
   expectedVersion: z.number().int().positive().optional(),
 });
@@ -78,20 +76,27 @@ export const contentRouter = {
         })
         .transform((v) => ({ ...v, spaceId: v.filter.spaceId })),
     )
-    .handler(async ({ input, context }) =>
-      context.content.list(
-        input.filter,
+    .handler(async ({ input, context }) => {
+      // A role that reads type by type sees only those types; asked for one it may not
+      // read, the answer is an empty page rather than a refusal.
+      const filter = narrowToAllowed(context, input.filter);
+      if (!filter) {
+        const pagination = input.pagination ?? { limit: 25, offset: 0 };
+        return { items: [], total: 0, ...pagination };
+      }
+      return context.content.list(
+        filter,
         input.pagination ?? { limit: 25, offset: 0 },
         input.sort ?? [],
         { actor: toActor(context, input.filter.spaceId) },
-      ),
-    ),
+      );
+    }),
 
   tree: scoped('content:read')
     .input(
       z.object({
         spaceId: uuid,
-        locale: z.string().default('en'),
+        locale: locale.default('en'),
         rootId: uuid.nullable().default(null),
       }),
     )
@@ -101,44 +106,53 @@ export const contentRouter = {
 
   get: scoped('content:read')
     .input(z.object({ spaceId: uuid, id: uuid }))
-    .handler(async ({ input, context }) =>
-      context.content.get(input.id, { actor: toActor(context, input.spaceId) }),
-    ),
+    .handler(async ({ input, context }) => {
+      await assertOnDocument(context, input.spaceId, 'content:read', input.id);
+      return context.content.get(input.id, { actor: toActor(context, input.spaceId) });
+    }),
 
   /** Field values with defaults filled in — what the editor opens a new document with. */
   blank: scoped('content:read')
     .input(z.object({ spaceId: uuid, typeId: uuid }))
-    .handler(async ({ input, context }) => ({
-      fields: await context.content.initFields(context.manablox.contentTypes.get(input.typeId)),
-    })),
+    .handler(async ({ input, context }) => {
+      assertOnType(context, input.spaceId, 'content:read', input.typeId);
+      return {
+        fields: await context.content.initFields(context.manablox.contentTypes.get(input.typeId)),
+      };
+    }),
 
   create: scoped('content:write')
     .input(saveSchema)
-    .handler(async ({ input, context }) =>
-      context.content.create(input, toActor(context, input.spaceId)),
-    ),
+    .handler(async ({ input, context }) => {
+      assertOnType(context, input.spaceId, 'content:write', input.typeId);
+      return context.content.create(input, toActor(context, input.spaceId));
+    }),
 
   update: scoped('content:write')
     .input(saveSchema.extend({ id: uuid }))
-    .handler(async ({ input, context }) =>
-      context.content.update(input.id, input, toActor(context, input.spaceId)),
-    ),
+    .handler(async ({ input, context }) => {
+      assertOnType(context, input.spaceId, 'content:write', input.typeId);
+      return context.content.update(input.id, input, toActor(context, input.spaceId));
+    }),
 
   delete: scoped('content:delete')
     .input(z.object({ spaceId: uuid, id: uuid }))
-    .handler(async ({ input, context }) => ({
-      deleted: await context.content.delete(input.id, toActor(context, input.spaceId)),
-    })),
+    .handler(async ({ input, context }) => {
+      await assertOnDocument(context, input.spaceId, 'content:delete', input.id);
+      return { deleted: await context.content.delete(input.id, toActor(context, input.spaceId)) };
+    }),
 
   publish: scoped('content:publish')
     .input(z.object({ spaceId: uuid, id: uuid }))
-    .handler(async ({ input, context }) =>
-      context.content.publish(input.id, toActor(context, input.spaceId)),
-    ),
+    .handler(async ({ input, context }) => {
+      await assertOnDocument(context, input.spaceId, 'content:publish', input.id);
+      return context.content.publish(input.id, toActor(context, input.spaceId));
+    }),
 
   unpublish: scoped('content:publish')
     .input(z.object({ spaceId: uuid, id: uuid }))
     .handler(async ({ input, context }) => {
+      await assertOnDocument(context, input.spaceId, 'content:publish', input.id);
       await context.content.unpublish(input.id, toActor(context, input.spaceId));
       return { ok: true };
     }),
@@ -153,9 +167,10 @@ export const contentRouter = {
         position: z.number().int().min(0),
       }),
     )
-    .handler(async ({ input, context }) =>
-      context.content.move(input.spaceId, input.id, input.parentId, input.position),
-    ),
+    .handler(async ({ input, context }) => {
+      await assertOnDocument(context, input.spaceId, 'content:write', input.id);
+      return context.content.move(input.spaceId, input.id, input.parentId, input.position);
+    }),
 
   /** Every locale a document exists in, for the editor's language switcher. */
   translations: scoped('content:read')
@@ -164,15 +179,16 @@ export const contentRouter = {
 
   /** Starts a translation of an existing document, in the localization group it shares. */
   createTranslation: scoped('content:write')
-    .input(z.object({ spaceId: uuid, id: uuid, locale: z.string().min(2).max(10) }))
-    .handler(async ({ input, context }) =>
-      context.content.createTranslation(
+    .input(z.object({ spaceId: uuid, id: uuid, locale }))
+    .handler(async ({ input, context }) => {
+      await assertOnDocument(context, input.spaceId, 'content:write', input.id);
+      return context.content.createTranslation(
         input.spaceId,
         input.id,
         input.locale,
         toActor(context, input.spaceId),
-      ),
-    ),
+      );
+    }),
 
   versions: scoped('content:read')
     .input(z.object({ spaceId: uuid, id: uuid }))
@@ -186,11 +202,61 @@ export const contentRouter = {
 
   restore: scoped('content:write')
     .input(z.object({ spaceId: uuid, id: uuid, version: z.number().int().positive() }))
-    .handler(async ({ input, context }) =>
-      context.content.restore(input.id, input.version, toActor(context, input.spaceId)),
-    ),
+    .handler(async ({ input, context }) => {
+      await assertOnDocument(context, input.spaceId, 'content:write', input.id);
+      return context.content.restore(input.id, input.version, toActor(context, input.spaceId));
+    }),
 };
 
+// ---------------------------------------------------------------------------
+// Per-type permissions
+//
+// `scoped('content:…')` admits anyone whose role holds the action for *some* type; which
+// type is only known once the input, or the document it names, is in hand. These finish
+// the check.
+// ---------------------------------------------------------------------------
+
+function assertOnType(
+  context: RpcContext,
+  spaceId: string,
+  permission: ContentPermission,
+  typeId: string,
+): void {
+  try {
+    assertCan(context.principal, spaceId, permission, typeId);
+  } catch (error) {
+    throw toOrpcError(error);
+  }
+}
+
+async function assertOnDocument(
+  context: RpcContext,
+  spaceId: string,
+  permission: ContentPermission,
+  id: string,
+): Promise<void> {
+  // Only when the role narrows the action: the common case costs no extra read.
+  if (allowedTypeIds(context.principal, spaceId, permission) === null) return;
+  const row = await context.repos.content.findById(id);
+  if (!row || row.spaceId !== spaceId) {
+    throw toOrpcError(ManabloxError.notFound('content.notFound', { id }));
+  }
+  assertOnType(context, spaceId, permission, row.typeId);
+}
+
+/** The filter narrowed to the types the caller may read; `null` when that leaves none. */
+function narrowToAllowed<T extends { spaceId: string; typeIds?: string[] | undefined }>(
+  context: RpcContext,
+  filter: T,
+): T | null {
+  const allowed = allowedTypeIds(context.principal, filter.spaceId, 'content:read');
+  if (allowed === null) return filter;
+  const typeIds = filter.typeIds?.length
+    ? filter.typeIds.filter((typeId) => allowed.includes(typeId))
+    : allowed;
+  return typeIds.length ? { ...filter, typeIds } : null;
+}
+
 export { base };
 
 function toActor(context: { principal: unknown }, spaceId: string) {

package/src/routers/menu.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { scoped } from '../base.js';
+import { locale, machineName, uuid } from '../schemas.js';
+
+const menuSchema = z.object({
+  name: z.string().min(1).max(200),
+  machineName,
+  description: z.string().max(2000).nullable().optional(),
+});
+
+/** One entry as the editor hands it over: a document by localization id, or a link. */
+export interface MenuItemInputShape {
+  id?: string | undefined;
+  localizationId?: string | null | undefined;
+  label?: string | null | undefined;
+  url?: string | null | undefined;
+  children?: MenuItemInputShape[] | undefined;
+}
+
+const menuItemSchema: z.ZodType<MenuItemInputShape> = z.lazy(() =>
+  z.object({
+    id: uuid.optional(),
+    localizationId: uuid.nullable().optional(),
+    label: z.string().max(200).nullable().optional(),
+    url: z.string().max(2000).nullable().optional(),
+    children: z.array(menuItemSchema).max(500).optional(),
+  }),
+);
+
+/**
+ * Menus. Each rule — the unique machine name, what an entry may point at — lives in
+ * `MenuService`; a procedure here is an input schema, a permission and one call.
+ */
+export const menuRouter = {
+  list: scoped('menu:read')
+    .input(z.object({ spaceId: uuid }))
+    .handler(async ({ input, context }) => context.menus.list(input.spaceId)),
+
+  /** The menu with its entries, each content entry resolved to the document in `locale`. */
+  get: scoped('menu:read')
+    .input(z.object({ spaceId: uuid, id: uuid, locale }))
+    .handler(async ({ input, context }) =>
+      context.menus.get(input.spaceId, input.id, input.locale),
+    ),
+
+  create: scoped('menu:write')
+    .input(menuSchema.extend({ spaceId: uuid }))
+    .handler(async ({ input, context }) => context.menus.create(input)),
+
+  update: scoped('menu:write')
+    .input(menuSchema.partial().extend({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => {
+      const { spaceId, id, ...data } = input;
+      return context.menus.update(spaceId, id, data);
+    }),
+
+  delete: scoped('menu:write')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => {
+      await context.menus.delete(input.spaceId, input.id);
+      return { ok: true };
+    }),
+
+  /** Replaces the whole entry tree; the editor saves a menu as one document. */
+  setItems: scoped('menu:write')
+    .input(z.object({ spaceId: uuid, id: uuid, items: z.array(menuItemSchema).max(500) }))
+    .handler(async ({ input, context }) =>
+      context.menus.setItems(input.spaceId, input.id, input.items),
+    ),
+
+  /** Menus a document is linked from, for the editor's hint. */
+  usedIn: scoped('menu:read')
+    .input(z.object({ spaceId: uuid, localizationId: uuid }))
+    .handler(async ({ input, context }) =>
+      context.menus.usedIn(input.spaceId, input.localizationId),
+    ),
+};