@classytic/arc 1.0.0

package/dist/presets/index.d.ts

@@ -0,0 +1,336 @@
+import { MultiTenantOptions } from './multiTenant.js';
+export { default as multiTenantPreset } from './multiTenant.js';
+import { P as PresetResult, j as IRequestContext, m as IControllerResponse, n as PaginatedResult, d as AnyRecord, o as ResourceConfig } from '../index-DkAW8BXh.js';
+import 'mongoose';
+import 'fastify';
+import '../types-B99TBmFV.js';
+
+/**
+ * Soft Delete Preset
+ *
+ * Adds routes for listing deleted items and restoring them.
+ */
+
+interface SoftDeleteOptions {
+    deletedField?: string;
+}
+declare function softDeletePreset(options?: SoftDeleteOptions): PresetResult;
+
+/**
+ * Slug Lookup Preset
+ *
+ * Adds a route to get resource by slug.
+ */
+
+interface SlugLookupOptions {
+    slugField?: string;
+}
+declare function slugLookupPreset(options?: SlugLookupOptions): PresetResult;
+
+/**
+ * Owned By User Preset
+ *
+ * Adds ownership validation for update/delete operations.
+ *
+ * BEHAVIOR:
+ * - On update/remove, sets _ownershipCheck on request
+ * - BaseController enforces ownership before mutation
+ * - Users can only modify resources where ownerField matches their ID
+ *
+ * BYPASS:
+ * - Users with bypassRoles (default: ['admin', 'superadmin']) skip check
+ * - Resources without the ownerField are not checked
+ *
+ * @example
+ * defineResource({
+ *   name: 'post',
+ *   presets: [{ name: 'ownedByUser', ownerField: 'authorId' }],
+ * });
+ *
+ * // User A cannot update/delete User B's posts
+ * // Admins can modify any post
+ */
+
+interface OwnedByUserOptions {
+    ownerField?: string;
+    bypassRoles?: string[];
+}
+declare function ownedByUserPreset(options?: OwnedByUserOptions): PresetResult;
+
+/**
+ * Tree Preset
+ *
+ * Adds routes for hierarchical tree structures.
+ */
+
+interface TreeOptions {
+    parentField?: string;
+}
+declare function treePreset(options?: TreeOptions): PresetResult;
+
+/**
+ * Audited Preset
+ *
+ * Adds createdBy/updatedBy tracking to resources.
+ * Works with the audit plugin for full change tracking.
+ *
+ * @example
+ * defineResource({
+ *   name: 'product',
+ *   presets: ['audited'],
+ *   // Fields createdBy, updatedBy auto-populated from user context
+ * });
+ */
+
+interface AuditedPresetOptions {
+    /** Field name for creator (default: 'createdBy') */
+    createdByField?: string;
+    /** Field name for updater (default: 'updatedBy') */
+    updatedByField?: string;
+}
+/**
+ * Audited preset - adds createdBy/updatedBy tracking
+ */
+declare function auditedPreset(options?: AuditedPresetOptions): PresetResult;
+
+/**
+ * Preset Type Interfaces
+ *
+ * TypeScript interfaces that document the controller methods required by each preset.
+ * These interfaces help with type safety when using presets.
+ *
+ * @example Using with custom controllers
+ * ```typescript
+ * import { BaseController } from '@classytic/arc';
+ * import type { ISoftDeleteController } from '@classytic/arc/presets';
+ *
+ * class ProductController extends BaseController<Product> implements ISoftDeleteController {
+ *   // TypeScript now ensures you have getDeleted() and restore() methods
+ * }
+ * ```
+ */
+
+/**
+ * Soft Delete Preset Interface
+ *
+ * Required when using the `softDelete` preset.
+ * BaseController provides default implementations that delegate to repository methods.
+ *
+ * **Routes Added:**
+ * - `GET /deleted` → `getDeleted()`
+ * - `POST /:id/restore` → `restore()`
+ *
+ * **Repository Requirements:**
+ * Your repository must implement:
+ * - `getDeleted(options): Promise<PaginatedResult<T> | T[]>`
+ * - `restore(id): Promise<T | null>`
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'product',
+ *   presets: ['softDelete'],
+ *   adapter: createMongooseAdapter({
+ *     model: ProductModel,
+ *     repository: productRepository, // Must implement getDeleted/restore
+ *   }),
+ * });
+ * ```
+ */
+interface ISoftDeleteController<TDoc = unknown> {
+    /**
+     * Get all soft-deleted items
+     * Called by: GET /deleted
+     */
+    getDeleted(context: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+    /**
+     * Restore a soft-deleted item by ID
+     * Called by: POST /:id/restore
+     */
+    restore(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
+}
+/**
+ * Slug Lookup Preset Interface
+ *
+ * Required when using the `slugLookup` preset.
+ * BaseController provides default implementation that delegates to repository.
+ *
+ * **Routes Added:**
+ * - `GET /slug/:slug` → `getBySlug()`
+ *
+ * **Repository Requirements:**
+ * Your repository must implement:
+ * - `getBySlug(slug, options): Promise<T | null>`
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'product',
+ *   presets: ['slugLookup'],
+ *   adapter: createMongooseAdapter({
+ *     model: ProductModel,
+ *     repository: productRepository, // Must implement getBySlug
+ *   }),
+ * });
+ * ```
+ */
+interface ISlugLookupController<TDoc = unknown> {
+    /**
+     * Get a resource by its slug
+     * Called by: GET /slug/:slug
+     */
+    getBySlug(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
+}
+/**
+ * Tree Preset Interface
+ *
+ * Required when using the `tree` preset for hierarchical data structures.
+ * BaseController provides default implementations that delegate to repository.
+ *
+ * **Routes Added:**
+ * - `GET /tree` → `getTree()`
+ * - `GET /:parent/children` → `getChildren()`
+ *
+ * **Repository Requirements:**
+ * Your repository must implement:
+ * - `getTree(options): Promise<T[]>`
+ * - `getChildren(parentId, options): Promise<T[]>`
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'category',
+ *   presets: [{ name: 'tree', parentField: 'parentId' }],
+ *   adapter: createMongooseAdapter({
+ *     model: CategoryModel,
+ *     repository: categoryRepository, // Must implement getTree/getChildren
+ *   }),
+ * });
+ * ```
+ */
+interface ITreeController<TDoc = unknown> {
+    /**
+     * Get the full hierarchical tree
+     * Called by: GET /tree
+     */
+    getTree(context: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+    /**
+     * Get direct children of a parent node
+     * Called by: GET /:parent/children
+     */
+    getChildren(context: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+}
+/**
+ * Owned By User Preset
+ *
+ * This preset does NOT require controller methods - it adds middleware only.
+ * Middleware automatically enforces ownership checks on update/delete operations.
+ *
+ * **Behavior:**
+ * - Users can only update/delete resources where `ownerField` matches their user ID
+ * - Admins (configurable via `bypassRoles`) can modify any resource
+ *
+ * **No controller interface needed** - ownership is enforced via middleware.
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'post',
+ *   presets: [{ name: 'ownedByUser', ownerField: 'authorId' }],
+ * });
+ * ```
+ */
+type IOwnedByUserPreset = never;
+/**
+ * Multi-Tenant Preset
+ *
+ * This preset does NOT require controller methods - it adds middleware only.
+ * Middleware automatically filters resources by organization/tenant ID.
+ *
+ * **Behavior:**
+ * - All list/get operations are automatically filtered by `tenantField`
+ * - Create operations automatically inject the tenant ID
+ * - Superadmins (configurable via `bypassRoles`) can access all tenants
+ *
+ * **No controller interface needed** - tenant isolation is enforced via middleware.
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'invoice',
+ *   presets: [{ name: 'multiTenant', tenantField: 'organizationId' }],
+ * });
+ * ```
+ */
+type IMultiTenantPreset = never;
+/**
+ * Audited Preset
+ *
+ * This preset does NOT require controller methods - it adds middleware only.
+ * Middleware automatically populates `createdBy`/`updatedBy` fields from authenticated user.
+ *
+ * **Behavior:**
+ * - On create: Sets both `createdBy` and `updatedBy` to current user ID
+ * - On update: Sets `updatedBy` to current user ID
+ * - Fields are marked as `systemManaged` in schemas (excluded from user input)
+ *
+ * **No controller interface needed** - audit fields are managed via middleware.
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'product',
+ *   presets: ['audited'], // Uses default fields: createdBy, updatedBy
+ * });
+ * ```
+ */
+type IAuditedPreset = never;
+/**
+ * Combined type for controllers using multiple presets
+ *
+ * @example
+ * ```typescript
+ * import type { IPresetController } from '@classytic/arc/presets';
+ *
+ * class ProductController
+ *   extends BaseController<Product>
+ *   implements IPresetController<Product, 'softDelete' | 'slugLookup' | 'tree'>
+ * {
+ *   // TypeScript ensures all required methods are implemented
+ * }
+ * ```
+ */
+type IPresetController<TDoc = unknown, TPresets extends 'softDelete' | 'slugLookup' | 'tree' | never = never> = TPresets extends 'softDelete' ? ISoftDeleteController<TDoc> : TPresets extends 'slugLookup' ? ISlugLookupController<TDoc> : TPresets extends 'tree' ? ITreeController<TDoc> : unknown;
+
+/**
+ * Convenience alias for multiTenantPreset with public list/get routes
+ * Equivalent to: multiTenantPreset({ allowPublic: ['list', 'get'] })
+ */
+declare const flexibleMultiTenantPreset: (options?: Omit<MultiTenantOptions, "allowPublic">) => PresetResult;
+
+type PresetFactory = (options?: AnyRecord) => PresetResult;
+/**
+ * Get preset by name with options
+ */
+declare function getPreset(nameOrConfig: string | {
+    name: string;
+    [key: string]: unknown;
+}): PresetResult;
+/**
+ * Register a custom preset
+ */
+declare function registerPreset(name: string, factory: PresetFactory): void;
+/**
+ * Get all available preset names
+ */
+declare function getAvailablePresets(): string[];
+type PresetInput = string | PresetResult | {
+    name: string;
+    [key: string]: unknown;
+};
+/**
+ * Apply presets to resource config
+ */
+declare function applyPresets<TDoc = AnyRecord>(config: ResourceConfig<TDoc>, presets?: PresetInput[]): ResourceConfig<TDoc>;
+
+export { type AuditedPresetOptions, type IAuditedPreset, type IMultiTenantPreset, type IOwnedByUserPreset, type IPresetController, type ISlugLookupController, type ISoftDeleteController, type ITreeController, MultiTenantOptions, type OwnedByUserOptions, type SlugLookupOptions, type SoftDeleteOptions, type TreeOptions, applyPresets, auditedPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };

package/dist/presets/index.js

@@ -0,0 +1,382 @@
+// src/permissions/index.ts
+function allowPublic() {
+  const check = () => true;
+  check._isPublic = true;
+  return check;
+}
+function requireRoles(roles, options) {
+  return (ctx) => {
+    if (!ctx.user) {
+      return { granted: false, reason: "Authentication required" };
+    }
+    const userRoles = ctx.user.roles ?? [];
+    if (roles.some((r) => userRoles.includes(r))) {
+      return true;
+    }
+    return {
+      granted: false,
+      reason: `Required roles: ${roles.join(", ")}`
+    };
+  };
+}
+
+// src/presets/softDelete.ts
+function softDeletePreset(options = {}) {
+  const { deletedField: _deletedField = "deletedAt" } = options;
+  return {
+    name: "softDelete",
+    additionalRoutes: (permissions) => [
+      {
+        method: "GET",
+        path: "/deleted",
+        handler: "getDeleted",
+        summary: "Get soft-deleted items",
+        permissions: permissions.list ?? requireRoles(["admin"]),
+        wrapHandler: true
+      },
+      {
+        method: "POST",
+        path: "/:id/restore",
+        handler: "restore",
+        summary: "Restore soft-deleted item",
+        permissions: permissions.update ?? requireRoles(["admin"]),
+        wrapHandler: true
+      }
+    ]
+  };
+}
+
+// src/presets/slugLookup.ts
+function slugLookupPreset(options = {}) {
+  const { slugField = "slug" } = options;
+  return {
+    name: "slugLookup",
+    additionalRoutes: (permissions) => [
+      {
+        method: "GET",
+        path: `/slug/:${slugField}`,
+        handler: "getBySlug",
+        summary: "Get by slug",
+        permissions: permissions.get ?? allowPublic(),
+        wrapHandler: true
+        // Handler is a ControllerHandler
+      }
+    ],
+    // Pass to controller so it knows which param to read
+    controllerOptions: {
+      slugField
+    }
+  };
+}
+
+// src/presets/ownedByUser.ts
+function createOwnershipCheck(ownerField, bypassRoles) {
+  return async (request, _reply) => {
+    const user = request.user;
+    if (!user) return;
+    const userWithRoles = user;
+    if (userWithRoles.roles && bypassRoles.some((r) => userWithRoles.roles.includes(r))) return;
+    const userWithId = user;
+    const userId = userWithId._id ?? userWithId.id;
+    if (userId) {
+      request._ownershipCheck = {
+        field: ownerField,
+        userId
+      };
+    }
+  };
+}
+function ownedByUserPreset(options = {}) {
+  const {
+    ownerField = "userId",
+    bypassRoles = ["admin", "superadmin"]
+  } = options;
+  const ownershipMiddleware = createOwnershipCheck(ownerField, bypassRoles);
+  return {
+    name: "ownedByUser",
+    middlewares: {
+      update: [ownershipMiddleware],
+      delete: [ownershipMiddleware]
+    }
+  };
+}
+
+// src/presets/multiTenant.ts
+function defaultExtractOrganizationId(request) {
+  const context = request.context;
+  if (context?.organizationId) {
+    return context.organizationId;
+  }
+  const user = request.user;
+  if (user?.organizationId) {
+    return user.organizationId;
+  }
+  if (user?.organization) {
+    const org = user.organization;
+    return org._id || org.id || org;
+  }
+  return null;
+}
+function createTenantFilter(tenantField, bypassRoles, extractOrganizationId) {
+  return async (request, reply) => {
+    const user = request.user;
+    if (!user) {
+      reply.code(401).send({
+        success: false,
+        error: "Unauthorized",
+        message: "Authentication required for multi-tenant resources"
+      });
+      return;
+    }
+    const userWithRoles = user;
+    if (userWithRoles.roles && bypassRoles.some((r) => userWithRoles.roles.includes(r))) return;
+    const orgId = extractOrganizationId(request);
+    if (!orgId) {
+      reply.code(403).send({
+        success: false,
+        error: "Forbidden",
+        message: "Organization context required for this operation"
+      });
+      return;
+    }
+    request.query = request.query ?? {};
+    request.query._policyFilters = {
+      ...request.query._policyFilters ?? {},
+      [tenantField]: orgId
+    };
+  };
+}
+function createFlexibleTenantFilter(tenantField, bypassRoles, extractOrganizationId) {
+  return async (request, reply) => {
+    const user = request.user;
+    const orgId = extractOrganizationId(request);
+    if (!orgId) {
+      return;
+    }
+    if (!user) {
+      reply.code(401).send({
+        success: false,
+        error: "Unauthorized",
+        message: "Authentication required for organization-scoped data"
+      });
+      return;
+    }
+    const userWithRoles = user;
+    if (userWithRoles.roles && bypassRoles.some((r) => userWithRoles.roles.includes(r))) {
+      return;
+    }
+    request.query = request.query ?? {};
+    request.query._policyFilters = {
+      ...request.query._policyFilters ?? {},
+      [tenantField]: orgId
+    };
+  };
+}
+function createTenantInjection(tenantField, extractOrganizationId) {
+  return async (request, reply) => {
+    const orgId = extractOrganizationId(request);
+    if (!orgId) {
+      reply.code(403).send({
+        success: false,
+        error: "Forbidden",
+        message: "Organization context required to create resources"
+      });
+      return;
+    }
+    if (request.body) {
+      request.body[tenantField] = orgId;
+    }
+  };
+}
+function multiTenantPreset(options = {}) {
+  const {
+    tenantField = "organizationId",
+    bypassRoles = ["superadmin"],
+    extractOrganizationId = defaultExtractOrganizationId,
+    allowPublic: allowPublic2 = []
+  } = options;
+  const strictTenantFilter = createTenantFilter(tenantField, bypassRoles, extractOrganizationId);
+  const flexibleTenantFilter = createFlexibleTenantFilter(tenantField, bypassRoles, extractOrganizationId);
+  const tenantInjection = createTenantInjection(tenantField, extractOrganizationId);
+  const getFilter = (route) => allowPublic2.includes(route) ? flexibleTenantFilter : strictTenantFilter;
+  return {
+    name: "multiTenant",
+    middlewares: {
+      list: [getFilter("list")],
+      get: [getFilter("get")],
+      create: [tenantInjection],
+      update: [getFilter("update")],
+      delete: [getFilter("delete")]
+    }
+  };
+}
+
+// src/presets/tree.ts
+function treePreset(options = {}) {
+  const { parentField = "parent" } = options;
+  return {
+    name: "tree",
+    additionalRoutes: (permissions) => [
+      {
+        method: "GET",
+        path: "/tree",
+        handler: "getTree",
+        summary: "Get hierarchical tree",
+        permissions: permissions.list ?? allowPublic(),
+        wrapHandler: true
+      },
+      {
+        method: "GET",
+        path: `/:${parentField}/children`,
+        handler: "getChildren",
+        summary: "Get children of parent",
+        permissions: permissions.list ?? allowPublic(),
+        wrapHandler: true
+      }
+    ],
+    // Pass to controller so it knows which param to read
+    controllerOptions: {
+      parentField
+    }
+  };
+}
+
+// src/presets/audited.ts
+function auditedPreset(options = {}) {
+  const { createdByField = "createdBy", updatedByField = "updatedBy" } = options;
+  const injectCreatedBy = async (request, _reply) => {
+    const userWithId = request.user;
+    if (userWithId?._id || userWithId?.id) {
+      const userId = userWithId._id ?? userWithId.id;
+      request.body[createdByField] = userId;
+      request.body[updatedByField] = userId;
+    }
+    return void 0;
+  };
+  const injectUpdatedBy = async (request, _reply) => {
+    const userWithId = request.user;
+    if (userWithId?._id || userWithId?.id) {
+      request.body[updatedByField] = userWithId._id ?? userWithId.id;
+    }
+    return void 0;
+  };
+  return {
+    name: "audited",
+    schemaOptions: {
+      fieldRules: {
+        [createdByField]: { systemManaged: true },
+        [updatedByField]: { systemManaged: true },
+        createdAt: { systemManaged: true },
+        updatedAt: { systemManaged: true }
+      }
+    },
+    middlewares: {
+      create: [injectCreatedBy],
+      update: [injectUpdatedBy]
+    }
+  };
+}
+
+// src/presets/index.ts
+var flexibleMultiTenantPreset = (options = {}) => multiTenantPreset({ ...options, allowPublic: ["list", "get"] });
+var presetRegistry = {
+  softDelete: softDeletePreset,
+  slugLookup: slugLookupPreset,
+  ownedByUser: ownedByUserPreset,
+  multiTenant: multiTenantPreset,
+  tree: treePreset,
+  audited: auditedPreset
+};
+function getPreset(nameOrConfig) {
+  if (typeof nameOrConfig === "object" && nameOrConfig.name) {
+    const { name, ...options } = nameOrConfig;
+    return resolvePreset(name, options);
+  }
+  return resolvePreset(nameOrConfig);
+}
+function resolvePreset(name, options = {}) {
+  const factory = presetRegistry[name];
+  if (!factory) {
+    const available = Object.keys(presetRegistry).join(", ");
+    throw new Error(
+      `Unknown preset: '${name}'
+Available presets: ${available}
+Docs: https://github.com/classytic/arc#presets`
+    );
+  }
+  return factory(options);
+}
+function registerPreset(name, factory) {
+  if (presetRegistry[name]) {
+    throw new Error(`Preset '${name}' already exists`);
+  }
+  presetRegistry[name] = factory;
+}
+function getAvailablePresets() {
+  return Object.keys(presetRegistry);
+}
+function applyPresets(config, presets = []) {
+  let result = { ...config };
+  for (const preset of presets) {
+    const resolved = resolvePresetInput(preset);
+    result = mergePreset(result, resolved);
+  }
+  return result;
+}
+function resolvePresetInput(preset) {
+  if (typeof preset === "object" && ("middlewares" in preset || "additionalRoutes" in preset)) {
+    return preset;
+  }
+  if (typeof preset === "object" && "name" in preset) {
+    const { name, ...options } = preset;
+    return resolvePreset(name, options);
+  }
+  return resolvePreset(preset);
+}
+function mergePreset(config, preset) {
+  const result = { ...config };
+  if (preset.additionalRoutes) {
+    const routes = typeof preset.additionalRoutes === "function" ? preset.additionalRoutes(config.permissions ?? {}) : preset.additionalRoutes;
+    result.additionalRoutes = [
+      ...result.additionalRoutes ?? [],
+      ...routes
+    ];
+  }
+  if (preset.middlewares) {
+    result.middlewares = result.middlewares ?? {};
+    for (const [op, mws] of Object.entries(preset.middlewares)) {
+      const key = op;
+      result.middlewares[key] = [
+        ...result.middlewares[key] ?? [],
+        ...mws ?? []
+      ];
+    }
+  }
+  if (preset.schemaOptions) {
+    result.schemaOptions = {
+      ...result.schemaOptions,
+      ...preset.schemaOptions
+    };
+  }
+  if (preset.controllerOptions) {
+    result._controllerOptions = {
+      ...result._controllerOptions,
+      ...preset.controllerOptions
+    };
+  }
+  if (preset.hooks && preset.hooks.length > 0) {
+    result._hooks = result._hooks ?? [];
+    for (const hook of preset.hooks) {
+      result._hooks.push({
+        presetName: preset.name,
+        operation: hook.operation,
+        phase: hook.phase,
+        handler: hook.handler,
+        priority: hook.priority
+      });
+    }
+  }
+  return result;
+}
+
+export { applyPresets, auditedPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };