@classytic/arc 1.1.0 → 2.1.2

package/dist/core/index.d.ts

@@ -1,220 +0,0 @@
-export { B as BaseController, a as BaseControllerOptions } from '../BaseController-DVAiHxEQ.js';
-import { RouteHandlerMethod, FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
-import { w as FastifyWithDecorators, B as CrudController, _ as CrudRouterOptions, d as RequestWithExtras, a as IRequestContext, c as IControllerResponse, I as IController } from '../index-B4t03KQ0.js';
-export { q as ResourceDefinition, p as defineResource } from '../index-B4t03KQ0.js';
-import { P as PermissionCheck } from '../types-B99TBmFV.js';
-import 'mongoose';
-
-/**
- * CRUD Router Factory
- *
- * Creates standard REST routes with permission-based access control.
- * Full TypeScript support with proper Fastify types.
- *
- * Features:
- * - Permission-based access control via PermissionCheck functions
- * - Organization scoping for multi-tenant routes
- * - Consistent route patterns
- * - Framework-agnostic controllers via adapter pattern
- */
-
-/**
- * Create CRUD routes for a controller
- *
- * @param fastify - Fastify instance with Arc decorators
- * @param controller - CRUD controller with handler methods
- * @param options - Router configuration
- */
-declare function createCrudRouter<TDoc = unknown>(fastify: FastifyWithDecorators, controller: CrudController<TDoc> | undefined, options?: CrudRouterOptions): void;
-/**
- * Helper to create org scoped middleware
- */
-declare function createOrgScopedMiddleware(instance: FastifyWithDecorators): RouteHandlerMethod[];
-/**
- * Create permission middleware from PermissionCheck
- * Useful for custom route registration
- */
-declare function createPermissionMiddleware(permission: PermissionCheck, resourceName: string, action: string): RouteHandlerMethod | null;
-
-/**
- * Action Router Factory (Stripe Pattern)
- *
- * Consolidates multiple state-transition endpoints into a single unified action endpoint.
- * Instead of separate endpoints for each action (approve, dispatch, receive, cancel),
- * this creates one endpoint: POST /:id/action
- *
- * Benefits:
- * - 40% fewer endpoints
- * - Consistent permission checking
- * - Self-documenting via action enum
- * - Type-safe action validation
- * - Single audit point for all state transitions
- *
- * @example
- * import { createActionRouter } from '@classytic/arc';
- * import { requireRoles } from '@classytic/arc/permissions';
- *
- * createActionRouter(fastify, {
- *   tag: 'Inventory - Transfers',
- *   actions: {
- *     approve: async (id, data, req) => transferService.approve(id, req.user),
- *     dispatch: async (id, data, req) => transferService.dispatch(id, data.transport, req.user),
- *     receive: async (id, data, req) => transferService.receive(id, data, req.user),
- *     cancel: async (id, data, req) => transferService.cancel(id, data.reason, req.user),
- *   },
- *   actionPermissions: {
- *     approve: requireRoles(['admin', 'warehouse-manager']),
- *     dispatch: requireRoles(['admin', 'warehouse-staff']),
- *     receive: requireRoles(['admin', 'store-manager']),
- *     cancel: requireRoles(['admin']),
- *   },
- *   actionSchemas: {
- *     dispatch: {
- *       transport: { type: 'object', properties: { driver: { type: 'string' } } }
- *     },
- *     cancel: {
- *       reason: { type: 'string', minLength: 10 }
- *     },
- *   }
- * });
- */
-
-/**
- * Action handler function
- * @param id - Resource ID
- * @param data - Action-specific data from request body
- * @param req - Full Fastify request object
- * @returns Action result (will be wrapped in success response)
- */
-type ActionHandler<TData = any, TResult = any> = (id: string, data: TData, req: RequestWithExtras) => Promise<TResult>;
-/**
- * Action router configuration
- */
-interface ActionRouterConfig {
-    /**
-     * OpenAPI tag for grouping routes
-     */
-    tag?: string;
-    /**
-     * Action handlers map
-     * @example { approve: (id, data, req) => service.approve(id), ... }
-     */
-    actions: Record<string, ActionHandler>;
-    /**
-     * Per-action permission checks (PermissionCheck functions)
-     * @example { approve: requireRoles(['admin', 'manager']), cancel: requireRoles(['admin']) }
-     */
-    actionPermissions?: Record<string, PermissionCheck>;
-    /**
-     * Per-action JSON schema for body validation
-     * @example { dispatch: { transport: { type: 'object' } } }
-     */
-    actionSchemas?: Record<string, Record<string, any>>;
-    /**
-     * Global permission check applied to all actions (if action-specific not defined)
-     */
-    globalAuth?: PermissionCheck;
-    /**
-     * Optional idempotency service
-     * If provided, will handle idempotency-key header
-     */
-    idempotencyService?: IdempotencyService;
-    /**
-     * Custom error handler for action execution failures
-     * @param error - The error thrown by action handler
-     * @param action - The action that failed
-     * @param id - The resource ID
-     * @returns Status code and error response
-     */
-    onError?: (error: Error, action: string, id: string) => {
-        statusCode: number;
-        error: string;
-        code?: string;
-    };
-}
-/**
- * Idempotency service interface
- * Apps can provide their own implementation
- */
-interface IdempotencyService {
-    check(key: string, payload: any): Promise<{
-        isNew: boolean;
-        existingResult?: any;
-    }>;
-    complete(key: string | undefined, result: any): Promise<void>;
-    fail(key: string | undefined, error: Error): Promise<void>;
-}
-/**
- * Create action-based state transition endpoint
- *
- * Registers: POST /:id/action
- * Body: { action: string, ...actionData }
- *
- * @param fastify - Fastify instance
- * @param config - Action router configuration
- */
-declare function createActionRouter(fastify: FastifyInstance, config: ActionRouterConfig): void;
-
-/**
- * Fastify Adapter for IController
- *
- * Converts between Fastify's request/reply and framework-agnostic IRequestContext/IControllerResponse.
- * This allows controllers implementing IController to work seamlessly with Fastify.
- */
-
-/**
- * Create IRequestContext from Fastify request
- *
- * Extracts framework-agnostic context from Fastify-specific request object
- */
-declare function createRequestContext(req: FastifyRequest): IRequestContext;
-/**
- * Send IControllerResponse via Fastify reply
- *
- * Converts framework-agnostic response to Fastify response
- * Applies field masking if specified in request
- */
-declare function sendControllerResponse<T>(reply: FastifyReply, response: IControllerResponse<T>, request?: FastifyRequest): void;
-/**
- * Create Fastify route handler from IController method
- *
- * Wraps framework-agnostic controller method in Fastify-specific handler
- *
- * @example
- * ```typescript
- * const controller = new BaseController(repository);
- *
- * // Create Fastify handler
- * const listHandler = createFastifyHandler(controller.list.bind(controller));
- *
- * // Register route
- * fastify.get('/products', listHandler);
- * ```
- */
-declare function createFastifyHandler<T>(controllerMethod: (req: IRequestContext) => Promise<IControllerResponse<T>>): (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-/**
- * Create Fastify adapters for all CRUD methods of an IController
- *
- * Returns Fastify-compatible handlers for each CRUD operation
- *
- * @example
- * ```typescript
- * const controller = new BaseController(repository);
- * const handlers = createCrudHandlers(controller);
- *
- * fastify.get('/', handlers.list);
- * fastify.get('/:id', handlers.get);
- * fastify.post('/', handlers.create);
- * fastify.patch('/:id', handlers.update);
- * fastify.delete('/:id', handlers.delete);
- * ```
- */
-declare function createCrudHandlers<TDoc>(controller: IController<TDoc>): {
-    list: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-    get: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-    create: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-    update: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-    delete: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-};
-
-export { type ActionHandler, type ActionRouterConfig, type IdempotencyService, createActionRouter, createCrudHandlers, createCrudRouter, createFastifyHandler, createOrgScopedMiddleware, createPermissionMiddleware, createRequestContext, sendControllerResponse };