@optiqlabs/onecms-types

Shared Zod schemas and TypeScript types for OneCMS — the same contracts the API validates and the Studio consumes. Use this package in browser apps, SDKs, or server code when you need runtime-safe parsing and aligned types with the HTTP API.

What it does

• Describes domain data — projects, posts, media, authors, platform settings, notifications, pagination, auth bodies, and more.
• Validates request/query shapes — e.g. listPostsQuerySchema, publicPostQuerySchema, createPostBodySchema, so client and server agree on allowed fields and defaults.
• Exports inferred types — z.infer<typeof postSchema> gives you Post, etc., without duplicating interfaces.
• Small utilities — helpers like toPlainRecord, sanitizeProjectSettingsForClient, pickAllowedFeatureFlags, pickAllowedProjectCapabilities, and feature-flag checks.

This package is pure validation/types — no HTTP client and no React. Pair it with @optiqlabs/onecms-sdk or your own fetch layer.

Install

npm install @optiqlabs/onecms-types zod

zod is a direct dependency; keep versions compatible with what this package was built against (see peerDependencies / lockfile in the repo if you hit mismatches).

How it works

1. Schemas are built with z.object, z.enum, .strict(), etc., and exported by name (e.g. postSchema, projectSchema).

2. Parse at boundaries — e.g. after fetch, or before sending a body:

   import { listPostsQuerySchema, postSchema } from "@optiqlabs/onecms-types";
   
   const query = listPostsQuerySchema.parse({
     page: 1,
     limit: 10,
     sort: "publishedAt",
     order: "desc",
   });
   
   const post = postSchema.parse(apiJson);

3. IDs — the API distinguishes:

   • projectId — public stable id used in URLs like /api/v1/projects/:projectId/...
   • Mongo document id — 24-char hex; types include projectObjectIdSchema and helpers where relevant.

Highlights (non-exhaustive)

| Area | Examples | | --------------- | ------------------------------------------------------------------------------------------------------ | | Core entities | projectSchema, postSchema, mediaSchema, userSchema | | Platform / site | platformSettingsPublicSchema, platformSettingsPatchSchema, platformThemeSchema | | Public API | listPostsQuerySchema, publicPostQuerySchema, publicSearchQuerySchema, contentFormatQuerySchema | | Authors | authorPublicSchema, createProjectAuthorBodySchema | | Notifications | notificationTypeSchema, listNotificationsQuerySchema, platformBroadcastBodySchema | | Feature flags | FEATURE_FLAG_KEYS, isFeatureEnabled, pickAllowedFeatureFlags |

Import what you need from the package entry — everything is exported from the compiled dist/index.js / typings.

Related packages

• @optiqlabs/onecms-sdk — typed client for the public Content API (uses these schemas for query validation).
• @optiqlabs/onecms-utils — TipTap/markdown/slug helpers (not included here).

License

See the OneCMS monorepo license for this package’s terms when published from source.