@murumets-ee/content-api 0.1.0

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0 (ELv2)
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your
+licenses to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct the management and policies of an entity (for example, by
+voting right, contract, or otherwise). Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,15 @@
+# @murumets-ee/content-api
+
+Read-only REST API for frontend consumption — schema endpoint, CORS, caching, and permission gating.
+
+Part of [Lumi CMS](https://github.com/murumets-ee/lumi-cms) — a modular, type-safe CMS toolkit for Node.js.
+
+## Install
+
+```bash
+npm install @murumets-ee/content-api
+```
+
+## License
+
+[Elastic License 2.0 (ELv2)](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+import { PermissionChecker } from '@murumets-ee/core';
+import { Entity } from '@murumets-ee/entity';
+
+/**
+ * Content API — Public types
+ *
+ * All configuration, request, and response types for the read-only content API.
+ */
+
+/** CORS configuration — deny-by-default, explicit origin allowlist. */
+interface CorsConfig {
+    /** Allowed origins. Each matched exactly — no regex, no wildcards. */
+    allowedOrigins: string[];
+    /** Preflight cache max age (seconds). Default: 3600 */
+    maxAge?: number;
+}
+/** Per-entity cache override. */
+interface EntityCacheConfig {
+    /** Cache-Control max-age in seconds. */
+    maxAge?: number;
+    /** stale-while-revalidate window in seconds. */
+    staleWhileRevalidate?: number;
+    /** Whether this entity is cacheable. Default: true. Set false → no-store. */
+    cacheable?: boolean;
+}
+/** Global cache configuration. */
+interface CacheConfig {
+    /** Default max-age for all entities (seconds). Default: 60 */
+    defaultMaxAge?: number;
+    /** Default stale-while-revalidate (seconds). Default: 300 */
+    defaultStaleWhileRevalidate?: number;
+    /** Per-entity overrides, keyed by entity name. */
+    entities?: Record<string, EntityCacheConfig>;
+}
+/** Content API handler configuration. */
+interface ContentApiConfig {
+    /** Entity whitelist — ONLY these entities are queryable. Deny-by-default. */
+    entities: Entity[];
+    /**
+     * Permission checker — REQUIRED. Same pattern as admin API handler.
+     * Called lazily on first request, result cached with 30s TTL.
+     * Checks: `checker(role, entityName, 'view')` → boolean.
+     */
+    loadPermissions: () => Promise<PermissionChecker>;
+    /**
+     * Optional auth. Returns user role, or null for anonymous.
+     * When null or not provided → uses `publicRole`.
+     *
+     * Enables preview mode (e.g. bearer token → editor sees more entities).
+     */
+    authenticate?: (req: Request) => Promise<{
+        role: string;
+    } | null>;
+    /**
+     * Role for unauthenticated requests. Default: `'public'`.
+     * Must have explicit 'view' permission per entity to see anything.
+     */
+    publicRole?: string;
+    /** Default content locale for translation merging. */
+    defaultLocale?: string;
+    /** CORS configuration. Required when serving cross-origin. */
+    cors?: CorsConfig;
+    /** Cache-Control header configuration. */
+    cache?: CacheConfig;
+    /** Max pagination limit. Default: 100. Hard-capped at 100. */
+    maxLimit?: number;
+    /** Error hook for monitoring/logging. Errors are fire-and-forget. */
+    onError?: (err: {
+        status: number;
+        message: string;
+        entity?: string;
+        path: string;
+    }) => void;
+}
+interface ContentListResponse<T = Record<string, unknown>> {
+    data: T[];
+    meta: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+        /** Opaque cursor for fetching the next page via keyset pagination. */
+        nextCursor?: string;
+    };
+}
+interface ContentSingleResponse<T = Record<string, unknown>> {
+    data: T;
+}
+interface ContentCountResponse {
+    data: {
+        count: number;
+    };
+}
+interface ContentErrorResponse {
+    error: {
+        status: number;
+        message: string;
+        code: string;
+    };
+}
+/** Field metadata exposed by /_schema (public-safe subset of FieldConfig). */
+interface SchemaField {
+    type: string;
+    required?: boolean;
+    options?: readonly string[];
+    cardinality?: 'one' | 'many';
+}
+/** Entity metadata exposed by /_schema. */
+interface SchemaEntity {
+    name: string;
+    pluralName: string;
+    fields: Record<string, SchemaField>;
+}
+/** Full /_schema response. */
+interface SchemaResponse {
+    entities: SchemaEntity[];
+}
+/** Next.js catch-all route context shape. */
+interface RouteContext {
+    params: Promise<{
+        path: string[];
+    }>;
+}
+
+/**
+ * Content API handler factory
+ *
+ * Creates a read-only catch-all route handler for public content delivery.
+ * Mirrors the `createAdminApiHandler` pattern but with:
+ * - No mutations (GET + OPTIONS only)
+ * - Permission-gated (public role starts with 0 permissions)
+ * - Published content only (QueryClient auto-filters)
+ * - CORS + Cache-Control headers
+ *
+ * @example
+ * ```typescript
+ * // app/api/content/[...path]/route.ts
+ * import { createContentApiHandler } from '@murumets-ee/content-api'
+ * import { Article, Page } from '@/entities'
+ *
+ * const handler = createContentApiHandler({
+ *   entities: [Article, Page],
+ *   loadPermissions: async () => {
+ *     const roles = await loadRoles(getApp())
+ *     return buildPermissionChecker(roles)
+ *   },
+ *   cors: { allowedOrigins: ['https://www.example.com'] },
+ * })
+ *
+ * export const { GET, OPTIONS } = handler
+ * ```
+ */
+
+declare function createContentApiHandler(config: ContentApiConfig): {
+    GET: (req: Request, ctx: RouteContext) => Promise<Response>;
+    OPTIONS: (req: Request) => Response;
+};
+
+/**
+ * Schema introspection endpoint — GET /_schema
+ *
+ * Returns public-safe entity metadata for SDK generation.
+ * Only exposes: type, required, options (select), cardinality (reference).
+ * Internal fields (_version, _scopeId) excluded.
+ * No hooks, behaviors, access rules, or implementation details.
+ *
+ * Response is filtered by the caller's role permissions — only entities
+ * the role can 'view' are included.
+ */
+
+/** Convert an Entity to public-safe schema metadata. */
+declare function toSchemaEntity(entity: Entity): SchemaEntity;
+/**
+ * Build the full /_schema response.
+ * Only includes entities that pass the permission check.
+ */
+declare function buildSchemaResponse(entities: Entity[], checkPermission: (entityName: string) => boolean): SchemaResponse;
+
+export { type CacheConfig, type ContentApiConfig, type ContentCountResponse, type ContentErrorResponse, type ContentListResponse, type ContentSingleResponse, type CorsConfig, type EntityCacheConfig, type RouteContext, type SchemaEntity, type SchemaField, type SchemaResponse, buildSchemaResponse, createContentApiHandler, toSchemaEntity };

package/dist/index.js

@@ -0,0 +1 @@
+import {getApp}from'@murumets-ee/core';import {schemaRegistry}from'@murumets-ee/db';import {CountCache,decodeCursor,encodeCursor,estimateRowCount}from'@murumets-ee/entity';import {QueryClient}from'@murumets-ee/entity/query';import {and,eq,or,inArray,ilike,gte,lte,desc,asc}from'drizzle-orm';import {z}from'zod';function v(t,e){let n=e?.entities?.[t];if(n?.cacheable===false)return {"Cache-Control":"no-store"};let o=n?.maxAge??e?.defaultMaxAge??60,c=n?.staleWhileRevalidate??e?.defaultStaleWhileRevalidate??300;return {"Cache-Control":`public, max-age=${o}, stale-while-revalidate=${c}`}}function B(t,e){if(!e)return {};let n=t.headers.get("Origin");return n?e.allowedOrigins.includes(n)?{"Access-Control-Allow-Origin":n,"Access-Control-Allow-Methods":"GET, OPTIONS","Access-Control-Allow-Headers":"Content-Type, Accept, Authorization","Access-Control-Max-Age":String(e.maxAge??3600),Vary:"Origin"}:{}:{}}function ne(t,e){let n=B(t,e);return new Response(null,{status:204,headers:n})}var $=100,re=z.object({limit:z.coerce.number().int().min(1).max($).default(20),offset:z.coerce.number().int().min(0).default(0),sort:z.string().regex(/^-?[a-zA-Z_]+$/).optional(),locale:z.string().regex(/^[a-z]{2}(-[A-Z]{2})?$/).optional(),fields:z.string().optional(),search:z.string().max(200).optional(),cursor:z.string().max(500).optional()}),Z=z.object({locale:z.string().regex(/^[a-z]{2}(-[A-Z]{2})?$/).optional(),fields:z.string().optional()}),se=z.object({locale:z.string().regex(/^[a-z]{2}(-[A-Z]{2})?$/).optional()});function ie(t){return t.replace(/[%_\\]/g,"\\$&")}var Ce=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;function oe(t,e){switch(t.type){case "boolean":return e==="true"?true:e==="false"?false:null;case "reference":case "media":return Ce.test(e)?e:null;case "select":return t.options.includes(e)?e:null;case "date":return e;case "text":case "number":return e;default:return null}}function D(t,e){if(!t)return;let o=t.split(",").map(c=>c.trim()).filter(c=>c in e&&!c.startsWith("_")&&e[c].type!=="blocks");return o.length>0&&!o.includes("id")&&o.unshift("id"),o.length>0?o:void 0}function E(t,e=200,n){return new Response(JSON.stringify(t),{status:e,headers:{"Content-Type":"application/json",...n}})}function S(t,e,n,o){return E({error:{status:n,message:t,code:e}},n,o)}function P(t){return S("Not found","NOT_FOUND",404,t)}function Re(t){let e={type:t.type};return t.required&&(e.required=true),t.type==="select"&&(e.options=t.options),t.type==="reference"&&(e.cardinality=t.cardinality),e}function ae(t){let e=t.allFields,n={};for(let[o,c]of Object.entries(e))o.startsWith("_")||(n[o]=Re(c));return {name:t.name,pluralName:`${t.name}s`,fields:n}}function G(t,e){return {entities:t.filter(o=>e(o.name)).map(ae)}}function Te(t){let e=new Map;for(let n of t)e.set(n.name,n),e.set(`${n.name}s`,n);return e}function ve(t,e){let n=schemaRegistry.get(t.name);if(!n)return;let o=t.allFields;for(let[c,f]of Object.entries(o))if(f.type==="text"&&(f.indexed||f.required)){let u=n[c];if(u)return ilike(u,`%${ie(e)}%`)}}function Me(t,e,n){if(!e)return;let o=e.startsWith("-"),c=o?e.slice(1):e,f=n[c];if(!f||f.type==="blocks")return;let u=schemaRegistry.get(t);if(!(!u||!u[c]))return o?desc(u[c]):asc(u[c])}function Ne(t,e,n){let o=schemaRegistry.get(t);if(!o)return [];let c=[];for(let[f,u]of e.searchParams.entries()){let W=f.match(/^filter\[([a-zA-Z_]+)\]$/);if(!W)continue;let N=W[1],O=n[N];if(!O||O.type==="blocks")continue;let F=o[N];if(!F)continue;if(O.type==="date"){u.startsWith("gte:")?c.push(gte(F,u.slice(4))):u.startsWith("lte:")?c.push(lte(F,u.slice(4))):c.push(eq(F,u));continue}let L=oe(O,u);L!==null&&c.push(eq(F,L));}return c}function _e(t){let{entities:e,defaultLocale:n,publicRole:o="public",cors:c,cache:f,onError:u}=t,W=Math.min(t.maxLimit??$,$),N=Te(e),O=new CountCache(5e3),F=3e4,L=null,K=0;async function ce(){let i=Date.now();return (!L||i-K>F)&&(L=await t.loadPermissions(),K=i),L}async function le(i){if(!t.authenticate)return o;try{return (await t.authenticate(i))?.role??o}catch{return o}}function Y(i,r,a){return i(r,a,"view")}function q(i){let r=getApp();return new QueryClient({entity:i,db:r.db.readOnly,logger:r.logger.child({entity:i.name}),countCache:O})}async function ue(i,r,a){let s=new URL(i.url),p=re.safeParse(Object.fromEntries(s.searchParams));if(!p.success)return S("Invalid query parameters","VALIDATION_ERROR",400,a);let{limit:g,offset:d,sort:l,locale:h,fields:R,search:x,cursor:A}=p.data,y=Math.min(g,W),T=r.allFields,I;if(A){let C=decodeCursor(A);if(!C)return S("Invalid cursor","VALIDATION_ERROR",400,a);if(!(C.field in T)&&C.field!=="id")return S("Invalid cursor field","VALIDATION_ERROR",400,a);I=C;}let b=[];if(x){let C=ve(r,x);C&&b.push(C);}let V=Ne(r.name,s,T);b.push(...V);let w=Me(r.name,l,T),H=D(R,T),_=q(r),z=h??n,Q={where:b.length>0?and(...b):void 0,limit:y,offset:d,orderBy:w,select:H,locale:z,defaultLocale:n,cursor:I},[j,ee]=await Promise.all([_.findMany(Q),_.count({where:b.length>0?and(...b):void 0})]),te;if(j.length>0&&j.length===y){let C=j[j.length-1],U=I?.field??(l?l.startsWith("-")?l.slice(1):l:void 0),he=I?.direction??(l?.startsWith("-")?"desc":"asc");U&&C[U]!==void 0&&(te=encodeCursor(C,U,he));}let ge={...a,...v(r.name,f)};return E({data:j,meta:{total:ee,limit:y,offset:d,hasMore:d+y<ee,nextCursor:te}},200,ge)}async function de(i,r,a){let s=new URL(i.url);if(!se.safeParse(Object.fromEntries(s.searchParams)).success)return S("Invalid query parameters","VALIDATION_ERROR",400,a);if(s.searchParams.get("countMode")==="estimate"){let h=getApp(),R=await estimateRowCount(h.db.readOnly,r.name);return E({data:{count:R,estimate:true}},200,{...a,...v(r.name,f)})}let l=await q(r).count();return E({data:{count:l}},200,{...a,...v(r.name,f)})}async function fe(i,r,a,s){let p=new URL(i.url),g=Z.safeParse(Object.fromEntries(p.searchParams));if(!g.success)return S("Invalid query parameters","VALIDATION_ERROR",400,s);let{locale:d,fields:l}=g.data,h=r.allFields,R=D(l,h),x=d??n,y=await q(r).findById(a,{select:R,locale:x,defaultLocale:n});return y?E({data:y},200,{...s,...v(r.name,f)}):P(s)}async function me(i,r,a,s){let p=new URL(i.url),g=Z.safeParse(Object.fromEntries(p.searchParams));if(!g.success)return S("Invalid query parameters","VALIDATION_ERROR",400,s);let d=r.allFields;if(!d.slug)return P(s);let{locale:l,fields:h}=g.data,R=D(h,d),x=l??n,A=schemaRegistry.get(r.name);if(!A?.slug)return P(s);let y=q(r),T=d.slug,I=eq(A.slug,a);if(T.translatable&&x){let V=`${r.name}_translations`,w=schemaRegistry.get(V);if(w?.slug){let _=await getApp().db.readOnly.select({entityId:w.entityId}).from(w).where(and(eq(w.slug,a),eq(w.locale,x)));if(_.length>0){let z=_.map(Q=>Q.entityId);I=or(inArray(A.id,z),eq(A.slug,a));}}}let b=await y.findMany({where:I,limit:1,select:R,locale:x,defaultLocale:n});return b.length===0?P(s):E({data:b[0]},200,{...s,...v(r.name,f)})}async function pe(i,r){let a=B(i,c);try{let s=await r.params.then(h=>h.path);if(!s||s.length===0)return P(a);let p=await le(i),g=await ce();if(s[0]==="_schema"){let h=G(e,R=>Y(g,p,R));return E(h,200,{...a,"Cache-Control":"no-store"})}let d=s[0],l=N.get(d)??N.get(d.endsWith("s")?d.slice(0,-1):d);return !l||!Y(g,p,l.name)?P(a):s.length===1?ue(i,l,a):s[1]==="count"?de(i,l,a):s[1]==="slug"&&s[2]?me(i,l,s[2],a):s.length===2?fe(i,l,s[1],a):P(a)}catch(s){let p=s instanceof Error?s.message:"Internal server error";return console.error("[content-api] handler error:",s),u?.({status:500,message:p,path:new URL(i.url).pathname}),S("Internal server error","INTERNAL_ERROR",500,a)}}return {GET:(i,r)=>pe(i,r),OPTIONS:i=>ne(i,c)}}export{G as buildSchemaResponse,_e as createContentApiHandler,ae as toSchemaEntity};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@murumets-ee/content-api",
+  "version": "0.1.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "drizzle-orm": "^0.45.1",
+    "zod": "^3.24.1",
+    "@murumets-ee/core": "0.1.0",
+    "@murumets-ee/entity": "0.1.0",
+    "@murumets-ee/db": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest"
+  }
+}