@rangka/core 0.1.0 → 0.1.2

package/src/api/handlers.ts

@@ -1,274 +0,0 @@
-/* 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

@@ -1,27 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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

@@ -1,254 +0,0 @@
-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

@@ -1,99 +0,0 @@
-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 };
-}