@rangka/core 0.0.1

package/src/api/handlers.ts

@@ -0,0 +1,274 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { Kysely } from 'kysely';
+import type { ResolvedModel } from '../schema/types.js';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { ModelAccessOptions } from '../model-api/types.js';
+import { createModelAccess } from '../model-api/index.js';
+import { QueryParser, QueryValidationError } from './query-parser.js';
+import { resolveIncludes } from './include-resolver.js';
+import { getAuthContext } from '../auth/session.js';
+import { isOwnerOnly, modelHasCreatedBy } from '../auth/model-permissions.js';
+import { validateFields } from '../validation/field-validator.js';
+import { toBool } from '../helpers/coerce.js';
+import { assertOwnership } from '../helpers/assert-ownership.js';
+import { stampCreate, stampUpdate } from '../helpers/stamping.js';
+import { findMissingRequiredFields } from '../helpers/validation.js';
+import { BadRequestError, ForbiddenError, NotFoundError } from '../errors.js';
+
+// ---------- Types ----------
+
+/** Shared dependencies passed to each handler factory. */
+export interface HandlerContext {
+  model: ResolvedModel;
+  registry: SchemaRegistry;
+  db: Kysely<any>;
+  modelAccessOpts: Omit<ModelAccessOptions, 'auth'>;
+}
+
+// ---------- Internal helpers ----------
+
+/** Creates a QueryParser configured with the model's fields and relationship names. */
+function createParserForModel(ctx: HandlerContext): QueryParser {
+  const relationFieldNames = ctx.registry
+    .getRelationshipsForModel(ctx.model.qualifiedName)
+    .map((r) => r.field);
+  return new QueryParser(ctx.model.fields, relationFieldNames);
+}
+
+/** Validates that the request body is a non-null object. Throws BadRequestError if invalid. */
+function parseRequestBody(request: FastifyRequest): Record<string, unknown> {
+  const body = request.body as Record<string, unknown> | undefined;
+  if (!body || typeof body !== 'object') {
+    throw new BadRequestError('VALIDATION_ERROR', 'Request body is required');
+  }
+  return body;
+}
+
+// ---------- Route handler factories ----------
+
+/** GET /model — Returns a paginated list of records with filtering, sorting, and field selection. */
+export function listHandler(ctx: HandlerContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    try {
+      const parser = createParserForModel(ctx);
+      const parsed = parser.parse(request.query as Record<string, unknown>);
+      const includeArchived = toBool((request.query as any).includeArchived);
+
+      const authContext = getAuthContext(request);
+      const models = createModelAccess({ ...ctx.modelAccessOpts, auth: authContext });
+
+      const ownerRead = isOwnerOnly(authContext.permissions, ctx.model.qualifiedName, 'read');
+      if (ownerRead && !modelHasCreatedBy(ctx.model)) {
+        throw new ForbiddenError(
+          'FORBIDDEN',
+          `Owner-based read requires created_by field on ${ctx.model.qualifiedName}`,
+        );
+      }
+
+      let queryBuilder = models.query(ctx.model.qualifiedName);
+
+      if (includeArchived) {
+        queryBuilder = queryBuilder.includeArchived();
+      }
+
+      // Apply parsed filters directly (already translated by QueryParser)
+      queryBuilder = queryBuilder.filterRaw(parsed.filters);
+
+      // Apply search across searchable fields
+      if (parsed.search) {
+        const searchableFields = ctx.model.fields
+          .filter((f) => 'searchable' in f.config && f.config.searchable)
+          .map((f) => f.name);
+        if (searchableFields.length > 0) {
+          queryBuilder = queryBuilder.search(parsed.search, searchableFields);
+        }
+      }
+
+      // Apply owner-only filter
+      if (ownerRead) {
+        queryBuilder = queryBuilder.filter({ created_by: authContext.user!.id });
+      }
+
+      // Apply field selection
+      if (parsed.fields.length > 0) {
+        queryBuilder = queryBuilder.fields(parsed.fields);
+      }
+
+      // Apply sorting
+      for (const s of parsed.sort) {
+        queryBuilder = queryBuilder.sort(s.field, s.direction);
+      }
+
+      // Apply pagination
+      queryBuilder = queryBuilder.limit(parsed.pagination.limit).page(parsed.pagination.page);
+
+      const result = await queryBuilder.execWithMeta();
+
+      if (parsed.includes.length > 0) {
+        await resolveIncludes(
+          result.data,
+          parsed.includes,
+          ctx.registry,
+          ctx.db,
+          ctx.model.qualifiedName,
+          request,
+        );
+      }
+
+      return reply.send({ data: result.data, meta: result.meta });
+    } catch (err: any) {
+      if (err instanceof QueryValidationError) {
+        throw new BadRequestError(err.code, err.message);
+      }
+      throw err;
+    }
+  };
+}
+
+/** GET /model/:id — Returns a single record by ID with optional field selection. */
+export function getHandler(ctx: HandlerContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    try {
+      const { id } = request.params as { id: string };
+
+      const parser = createParserForModel(ctx);
+      const parsed = parser.parse(request.query as Record<string, unknown>);
+
+      const authContext = getAuthContext(request);
+      const models = createModelAccess({ ...ctx.modelAccessOpts, auth: authContext });
+
+      let queryBuilder = models.query(ctx.model.qualifiedName).filter({ id });
+
+      if (parsed.fields.length > 0) {
+        queryBuilder = queryBuilder.fields(parsed.fields);
+      }
+
+      const record = await queryBuilder.first();
+
+      if (!record) {
+        throw new NotFoundError(`Record not found: ${id}`);
+      }
+
+      if (isOwnerOnly(authContext.permissions, ctx.model.qualifiedName, 'read')) {
+        if (!modelHasCreatedBy(ctx.model) || record.created_by !== authContext.user?.id) {
+          throw new NotFoundError(`Record not found: ${id}`);
+        }
+      }
+
+      if (parsed.includes.length > 0) {
+        await resolveIncludes(
+          [record],
+          parsed.includes,
+          ctx.registry,
+          ctx.db,
+          ctx.model.qualifiedName,
+          request,
+        );
+      }
+
+      return reply.send({ data: record });
+    } catch (err: any) {
+      if (err instanceof QueryValidationError) {
+        throw new BadRequestError(err.code, err.message);
+      }
+      throw err;
+    }
+  };
+}
+
+/** POST /model — Creates a new record after validating required fields. */
+export function createHandler(ctx: HandlerContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const body = parseRequestBody(request);
+
+    // Validate required fields
+    const missing = findMissingRequiredFields(ctx.model, body);
+    if (missing.length > 0) {
+      throw new BadRequestError(
+        'VALIDATION_ERROR',
+        `Missing required fields: ${missing.join(', ')}`,
+        missing,
+      );
+    }
+
+    // Validate field rules
+    const violations = validateFields(ctx.model, body, 'create');
+    if (violations.length > 0) {
+      throw new BadRequestError(
+        'VALIDATION_ERROR',
+        violations.map((v) => v.message).join('; '),
+        violations,
+      );
+    }
+
+    const authContext = getAuthContext(request);
+    stampCreate(body, ctx.model, authContext);
+
+    const models = createModelAccess({ ...ctx.modelAccessOpts, auth: authContext });
+    const record = await models.create(ctx.model.qualifiedName, body);
+
+    return reply.status(201).send({ data: record });
+  };
+}
+
+/** PUT /model/:id — Updates an existing record after verifying it exists within auth scopes. */
+export function updateHandler(ctx: HandlerContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const { id } = request.params as { id: string };
+
+    const body = parseRequestBody(request);
+
+    // Validate field rules
+    const violations = validateFields(ctx.model, body, 'update');
+    if (violations.length > 0) {
+      throw new BadRequestError(
+        'VALIDATION_ERROR',
+        violations.map((v) => v.message).join('; '),
+        violations,
+      );
+    }
+
+    const authContext = getAuthContext(request);
+    const models = createModelAccess({ ...ctx.modelAccessOpts, auth: authContext });
+
+    // Verify record exists within auth scopes
+    const existing = await models.query(ctx.model.qualifiedName).filter({ id }).first();
+
+    if (!existing) {
+      throw new NotFoundError(`Record not found: ${id}`);
+    }
+
+    // Check owner-only permission
+    assertOwnership(authContext.permissions, ctx.model, existing, authContext.user?.id, 'write');
+
+    stampUpdate(body, ctx.model, authContext);
+    const record = await models.update(ctx.model.qualifiedName, id, body);
+
+    return reply.send({ data: record });
+  };
+}
+
+/** DELETE /model/:id — Deletes a record after verifying it exists within auth scopes. */
+export function deleteHandler(ctx: HandlerContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const { id } = request.params as { id: string };
+
+    const authContext = getAuthContext(request);
+    const models = createModelAccess({ ...ctx.modelAccessOpts, auth: authContext });
+
+    // Verify record exists within auth scopes
+    const existing = await models.query(ctx.model.qualifiedName).filter({ id }).first();
+
+    if (!existing) {
+      throw new NotFoundError(`Record not found: ${id}`);
+    }
+
+    // Check owner-only permission
+    assertOwnership(authContext.permissions, ctx.model, existing, authContext.user?.id, 'delete');
+
+    await models.delete(ctx.model.qualifiedName, id);
+
+    return reply.status(204).send();
+  };
+}

package/src/api/include-resolver.ts

@@ -0,0 +1,27 @@
+import type { Kysely } from 'kysely';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { ParsedInclude } from './query-parser.js';
+import {
+  resolveModelIncludes,
+  type IncludeSpec,
+  type IncludeResolverOptions,
+} from '../db/model-include-resolver.js';
+
+function toIncludeSpec(parsed: ParsedInclude): IncludeSpec {
+  if (!parsed.nested || parsed.nested.length === 0) return parsed.relation;
+  return { relation: parsed.relation, nested: parsed.nested.map(toIncludeSpec) };
+}
+
+export async function resolveIncludes(
+  records: Record<string, unknown>[],
+  includes: ParsedInclude[],
+  registry: SchemaRegistry,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: Kysely<any>,
+  sourceModel: string,
+  _request: unknown,
+  options?: IncludeResolverOptions,
+): Promise<void> {
+  const specs = includes.map(toIncludeSpec);
+  await resolveModelIncludes(records, specs, registry, db, sourceModel, options);
+}

package/src/api/index.ts

@@ -0,0 +1,4 @@
+export { createServer } from './server.js';
+export { QueryParser } from './query-parser.js';
+export { generateRoutes } from './route-generator.js';
+export type { ServerConfig, ApiDefinition } from './types.js';

package/src/api/meta-handler.ts

@@ -0,0 +1,254 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type {
+  ModuleConfig,
+  PageDefinition,
+  BootResponse,
+  ModelMeta,
+  FieldMeta,
+  NavigationTree,
+  NavigationTreeSection,
+  WidgetDefinitionMeta,
+  WidgetNode,
+} from '@rangka/shared';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { ResolvedPermissions } from '../auth/types.js';
+import type { ResolvedField } from '../schema/types.js';
+import { getAuthContext } from '../auth/session.js';
+import { UnauthorizedError } from '../errors.js';
+
+export interface MetaBootContext {
+  schemaRegistry: SchemaRegistry;
+  pages: Array<{ module: string; page: PageDefinition }>;
+  modules: ModuleConfig[];
+  widgets?: WidgetDefinitionMeta[];
+}
+
+/**
+ * Creates the GET /meta/boot handler that returns everything
+ * the client needs to render the shell: user info, permissions,
+ * navigation tree, page definitions, and model metadata.
+ */
+export function createMetaBootHandler(ctx: MetaBootContext) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const authCtx = getAuthContext(request);
+    if (!authCtx.user || !authCtx.permissions) {
+      throw new UnauthorizedError('Not authenticated');
+    }
+
+    const { user, permissions } = authCtx;
+    const accessiblePages = resolveAccessiblePages(ctx.pages, permissions);
+    const navigation = buildNavigationTree(ctx.modules, accessiblePages);
+    const models = buildModelMeta(accessiblePages, ctx.schemaRegistry);
+
+    const response: BootResponse = {
+      user: {
+        id: user.id,
+        name: user.full_name,
+        email: user.email,
+        roles: authCtx.roles ?? [],
+      },
+      permissions: {
+        models: permissions.models,
+        pages: permissions.pages,
+      },
+      navigation,
+      pages: accessiblePages.map((p) => p.page),
+      models,
+      widgets: ctx.widgets,
+    };
+
+    return reply.send(response);
+  };
+}
+
+// --- Page access resolution ---
+
+/**
+ * Filters pages to only those the user can access.
+ * A page is accessible if explicitly listed in page permissions,
+ * or if the user has read access to any model the page references.
+ */
+function resolveAccessiblePages(
+  pages: Array<{ module: string; page: PageDefinition }>,
+  permissions: ResolvedPermissions,
+): Array<{ module: string; page: PageDefinition }> {
+  return pages.filter(({ page }) => {
+    if (permissions.pages.includes(page.key)) {
+      return true;
+    }
+
+    const referencedModels = collectModelRefs(page);
+    if (referencedModels.length === 0) {
+      return true;
+    }
+
+    return referencedModels.some((model) => permissions.models[model]?.read === true);
+  });
+}
+
+/**
+ * Collects all model names referenced by a page's body widget tree.
+ */
+function collectModelRefs(page: PageDefinition): string[] {
+  const models = new Set<string>();
+
+  for (const node of page.body) {
+    collectModelRefsFromNode(node, models);
+  }
+
+  return Array.from(models);
+}
+
+/** Recursively collects model references from a widget node tree. */
+function collectModelRefsFromNode(node: WidgetNode, models: Set<string>): void {
+  if (node.source?.model) {
+    models.add(node.source.model);
+  }
+  if (node.bind?.model?.name) {
+    models.add(node.bind.model.name);
+  }
+  if (node.children) {
+    for (const child of node.children) {
+      collectModelRefsFromNode(child, models);
+    }
+  }
+}
+
+// --- Navigation tree ---
+
+/**
+ * Builds the navigation tree by filtering each module's nav sections
+ * down to only pages the user can access, then sorting by module order.
+ */
+function buildNavigationTree(
+  modules: ModuleConfig[],
+  accessiblePages: Array<{ module: string; page: PageDefinition }>,
+): NavigationTree[] {
+  const accessiblePageKeys = new Set(accessiblePages.map((p) => p.page.key));
+  const tree: NavigationTree[] = [];
+
+  for (const mod of modules) {
+    if (!mod.navigation) continue;
+
+    const sections = buildAccessibleSections(mod.navigation, accessiblePageKeys);
+    if (sections.length === 0) continue;
+
+    tree.push({
+      module: mod.name,
+      label: mod.label,
+      description: mod.description,
+      icon: mod.icon,
+      color: mod.color,
+      order: mod.order,
+      type: mod.type,
+      sections,
+    });
+  }
+
+  tree.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  return tree;
+}
+
+/** Filters a module's navigation sections to only include accessible pages. */
+function buildAccessibleSections(
+  navigation: NonNullable<ModuleConfig['navigation']>,
+  accessiblePageKeys: Set<string>,
+): NavigationTreeSection[] {
+  const sections: NavigationTreeSection[] = [];
+
+  for (const section of navigation) {
+    const visibleItems = section.items.filter((item) => accessiblePageKeys.has(item.page));
+    if (visibleItems.length === 0) continue;
+
+    sections.push({
+      section: section.section,
+      items: visibleItems.map((item) => ({
+        page: item.page,
+        label: item.label,
+        icon: item.icon,
+      })),
+    });
+  }
+
+  return sections;
+}
+
+// --- Model metadata ---
+
+/**
+ * Builds a map of model metadata for all models referenced by accessible pages.
+ */
+function buildModelMeta(
+  accessiblePages: Array<{ module: string; page: PageDefinition }>,
+  schemaRegistry: SchemaRegistry,
+): Record<string, ModelMeta> {
+  const referencedModelNames = new Set<string>();
+
+  for (const { page } of accessiblePages) {
+    for (const ref of collectModelRefs(page)) {
+      referencedModelNames.add(ref);
+    }
+  }
+
+  const result: Record<string, ModelMeta> = {};
+
+  for (const name of referencedModelNames) {
+    const model = schemaRegistry.getModel(name);
+    if (!model) continue;
+
+    result[name] = {
+      qualifiedName: model.qualifiedName,
+      label: model.label,
+      fields: model.fields.map((field) => resolvedFieldToMeta(field)),
+    };
+  }
+
+  return result;
+}
+
+/** Converts a resolved field definition into the client-facing FieldMeta shape. */
+function resolvedFieldToMeta(field: ResolvedField): FieldMeta {
+  const meta: FieldMeta = {
+    name: field.name,
+    type: field.config.type,
+  };
+
+  if ('label' in field.config && field.config.label) {
+    meta.label = field.config.label;
+  }
+
+  if ('required' in field.config && field.config.required) {
+    meta.required = true;
+  }
+
+  if ('searchable' in field.config && field.config.searchable) {
+    meta.searchable = true;
+  }
+
+  if (field.config.type === 'enum') {
+    meta.options = field.config.options;
+  }
+
+  // Attach relationship metadata based on field type
+  meta.relationship = extractRelationshipMeta(field.config);
+
+  return meta;
+}
+
+/** Extracts relationship metadata from a field config, or returns undefined for non-relational fields. */
+function extractRelationshipMeta(config: ResolvedField['config']): FieldMeta['relationship'] {
+  switch (config.type) {
+    case 'link':
+      return { type: 'link', model: config.model };
+    case 'hasMany':
+      return { type: 'hasMany', model: config.model, foreignKey: config.foreignKey };
+    case 'children':
+      return { type: 'children', model: config.model, foreignKey: config.foreignKey };
+    case 'manyToMany':
+      return { type: 'manyToMany', model: config.model, through: config.through };
+    case 'dynamicLink':
+      return { type: 'dynamicLink', modelField: config.modelField };
+    default:
+      return undefined;
+  }
+}

package/src/api/openapi-schema.ts

@@ -0,0 +1,99 @@
+import type { FieldConfig } from '@rangka/shared';
+import type { ResolvedModel } from '../schema/types.js';
+
+export interface JsonSchemaProperty {
+  type: string;
+  format?: string;
+  description?: string;
+  enum?: readonly string[];
+  items?: { type: string };
+}
+
+export interface JsonSchemaObject {
+  type: 'object';
+  properties: Record<string, JsonSchemaProperty>;
+  required?: string[];
+}
+
+/** Map a Rangka field type to its JSON Schema equivalent. Returns null for relation/computed types. */
+export function fieldToJsonSchema(config: FieldConfig): JsonSchemaProperty | null {
+  switch (config.type) {
+    case 'string':
+    case 'text':
+    case 'code':
+    case 'sequence':
+    case 'dynamicLink':
+      return { type: 'string' };
+    case 'int':
+      return { type: 'integer' };
+    case 'decimal':
+    case 'money':
+      return { type: 'number' };
+    case 'boolean':
+      return { type: 'boolean' };
+    case 'date':
+      return { type: 'string', format: 'date' };
+    case 'datetime':
+      return { type: 'string', format: 'date-time' };
+    case 'enum':
+      return { type: 'string', enum: config.options };
+    case 'json':
+      return { type: 'object' };
+    case 'link':
+      return { type: 'string', description: `Reference to ${config.model}` };
+    case 'attachment':
+      return { type: 'string', format: 'uri' };
+    case 'attachments':
+      return { type: 'array', items: { type: 'string' } };
+    // Relation and computed types have no direct JSON representation
+    case 'hasMany':
+    case 'children':
+    case 'manyToMany':
+    case 'tree':
+    case 'computed':
+      return null;
+  }
+}
+
+/** Build a full JSON Schema object for a model, including all serializable fields. */
+export function modelToSchemaComponent(model: ResolvedModel): JsonSchemaObject {
+  const properties: Record<string, JsonSchemaProperty> = {
+    id: { type: 'string', description: 'Primary key' },
+  };
+  const required: string[] = [];
+
+  for (const field of model.fields) {
+    const fieldSchema = fieldToJsonSchema(field.config);
+    if (!fieldSchema) continue;
+
+    const property: JsonSchemaProperty = { ...fieldSchema };
+    if ('label' in field.config && field.config.label) {
+      property.description = field.config.label;
+    }
+    properties[field.name] = property;
+
+    if ('required' in field.config && field.config.required) {
+      required.push(field.name);
+    }
+  }
+
+  const schema: JsonSchemaObject = { type: 'object', properties };
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  return schema;
+}
+
+/** Schema for creating a record — same as the full schema but without the `id` field. */
+export function modelToCreateSchema(model: ResolvedModel): JsonSchemaObject {
+  const full = modelToSchemaComponent(model);
+  const { id: _, ...properties } = full.properties;
+  return { type: 'object', properties };
+}
+
+/** Schema for updating a record — same as create (all fields optional, no `id`). */
+export function modelToUpdateSchema(model: ResolvedModel): JsonSchemaObject {
+  const full = modelToSchemaComponent(model);
+  const { id: _, ...properties } = full.properties;
+  return { type: 'object', properties };
+}