@classytic/arc 1.0.0 → 1.0.8

package/dist/core/index.d.ts

@@ -0,0 +1,220 @@
+export { B as BaseController, a as BaseControllerOptions } from '../BaseController-nNRS3vpA.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-D5QTob1X.js';
+export { q as ResourceDefinition, p as defineResource } from '../index-D5QTob1X.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 };