inviton-backduck 1.0.0

package/dist/apidoc/config.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Configuration for API Documentation Generator
+ */
+export declare class ApiDocConfig {
+    /** API metadata for OpenAPI info section */
+    static readonly title = "GoPass E-Shop API";
+    static readonly version = "1.0.0";
+    static readonly description = "API documentation for the GoPass e-commerce platform";
+    static readonly contact: {
+        name: string;
+        email: string;
+    };
+    /** Server URLs for different environments */
+    static readonly servers: {
+        development: {
+            url: string;
+            description: string;
+        };
+        staging: {
+            url: string;
+            description: string;
+        };
+        production: {
+            url: string;
+            description: string;
+        };
+    };
+    /** Base paths for API routes */
+    static readonly basePaths: {
+        shop: string;
+        admin: string;
+    };
+    /** Output directory paths (relative to server directory) */
+    static readonly output: {
+        /** Base directory for generated documentation */
+        baseDir: string;
+        /** Swagger UI output directory */
+        swaggerDir: string;
+        /** HTML documentation output directory */
+        htmlDir: string;
+        /** OpenAPI spec filename */
+        specFilename: string;
+    };
+    /** File patterns for controller discovery */
+    static readonly patterns: {
+        /** Pattern to find controller files */
+        controllerFiles: string;
+        /** Pattern to find router files */
+        routerFiles: string;
+        /** Pattern to find service interface files */
+        serviceInterfaceFiles: string;
+        /** Pattern to find args/dto files */
+        argsFiles: string;
+    };
+    /** Source directories (relative to server directory) */
+    static readonly sourceDirectories: {
+        /** Shop API controllers directory */
+        shopApi: string;
+        /** Admin API controllers directory */
+        adminApi: string;
+        /** Services directory */
+        services: string;
+    };
+    /** HTTP method mappings from controller method names */
+    static readonly httpMethodMappings: Record<string, string>;
+    /** Decorator names to look for */
+    static readonly decorators: {
+        route: string;
+        shopAuth: string;
+        shopEnterpriseAuth: string;
+        adminAuth: string;
+        rateLimit: string;
+        webMethod: string;
+    };
+    /** TypeScript types that need special handling in OpenAPI schema */
+    static readonly specialTypes: Record<string, object>;
+    /** Security scheme configuration for OpenAPI */
+    static readonly securitySchemes: {
+        shopApiAuth: {
+            type: "apiKey";
+            name: string;
+            in: "header";
+            description: string;
+        };
+        bearerAuth: {
+            type: "http";
+            scheme: string;
+            bearerFormat: string;
+            description: string;
+        };
+    };
+    /** Tag descriptions for endpoint grouping */
+    static readonly tagDescriptions: Record<string, string>;
+    /** Getting Started section content configuration */
+    static readonly gettingStarted: {
+        /** Introduction paragraph shown after the lead description */
+        introText: string;
+        /** API interfaces available (shown in URI structure table) */
+        apiInterfaces: {
+            name: string;
+            description: string;
+        }[];
+        /** Example resources for documentation */
+        exampleResources: string[];
+        /** HTTP headers configuration */
+        httpHeaders: {
+            name: string;
+            description: string;
+            example: string;
+        }[];
+        /** Authentication methods configuration */
+        authentication: {
+            /** Bearer token authentication details */
+            bearerToken: {
+                title: string;
+                description: string;
+                steps: string[];
+            };
+            /** API key authentication details */
+            apiKey: {
+                title: string;
+                description: string;
+                steps: string[];
+                note: string;
+            };
+        };
+    };
+    /**
+     * Get the current environment mode
+     */
+    static getMode: () => "development" | "production";
+    /**
+     * Get the appropriate server URL based on current environment
+     */
+    static getCurrentServerUrl: () => string;
+    /**
+     * Get absolute path for output directory
+     */
+    static getOutputPath: (serverDir: string, type: "swagger" | "html") => string;
+    /**
+     * Get absolute path for source directory
+     */
+    static getSourcePath: (serverDir: string, type: "shopApi" | "adminApi" | "services") => string;
+    /**
+     * Get HTTP method from controller method name
+     */
+    static getHttpMethod: (methodName: string) => string | null;
+    /**
+     * Get OpenAPI schema for special TypeScript types
+     */
+    static getSpecialTypeSchema: (typeName: string) => object | null;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/apidoc/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/apidoc/config.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,qBAAa,YAAY;IACxB,4CAA4C;IAC5C,MAAM,CAAC,QAAQ,CAAC,KAAK,uBAAuB;IAC5C,MAAM,CAAC,QAAQ,CAAC,OAAO,WAAW;IAClC,MAAM,CAAC,QAAQ,CAAC,WAAW,0DAA0D;IACrF,MAAM,CAAC,QAAQ,CAAC,OAAO;;;MAGrB;IAEF,6CAA6C;IAC7C,MAAM,CAAC,QAAQ,CAAC,OAAO;;;;;;;;;;;;;MAarB;IAEF,gCAAgC;IAChC,MAAM,CAAC,QAAQ,CAAC,SAAS;;;MAGvB;IAEF,4DAA4D;IAC5D,MAAM,CAAC,QAAQ,CAAC,MAAM;QACrB,iDAAiD;;QAEjD,kCAAkC;;QAElC,0CAA0C;;QAE1C,4BAA4B;;MAE3B;IAEF,6CAA6C;IAC7C,MAAM,CAAC,QAAQ,CAAC,QAAQ;QACvB,uCAAuC;;QAEvC,mCAAmC;;QAEnC,8CAA8C;;QAE9C,qCAAqC;;MAEpC;IAEF,wDAAwD;IACxD,MAAM,CAAC,QAAQ,CAAC,iBAAiB;QAChC,qCAAqC;;QAErC,sCAAsC;;QAEtC,yBAAyB;;MAExB;IAEF,wDAAwD;IACxD,MAAM,CAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxD;IAEF,kCAAkC;IAClC,MAAM,CAAC,QAAQ,CAAC,UAAU;;;;;;;MAOxB;IAEF,oEAAoE;IACpE,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA+BlD;IAEF,gDAAgD;IAChD,MAAM,CAAC,QAAQ,CAAC,eAAe;;;;;;;;;;;;;MAa7B;IAEF,6CAA6C;IAC7C,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWrD;IAEF,oDAAoD;IACpD,MAAM,CAAC,QAAQ,CAAC,cAAc;QAC7B,8DAA8D;;QAK9D,8DAA8D;;;;;QAM9D,0CAA0C;;QAO1C,iCAAiC;;;;;;QAwBjC,2CAA2C;;YAE1C,0CAA0C;;;;;;YAU1C,qCAAqC;;;;;;;;MAWrC;IAEF;;OAEG;IACH,MAAM,CAAC,OAAO,QAAO,aAAa,GAAG,YAAY,CAAyE;IAE1H;;OAEG;IACH,MAAM,CAAC,mBAAmB,QAAO,MAAM,CAQrC;IAEF;;OAEG;IACH,MAAM,CAAC,aAAa,GAAI,WAAW,MAAM,EAAE,MAAM,SAAS,GAAG,MAAM,KAAG,MAAM,CAI1E;IAEF;;OAEG;IACH,MAAM,CAAC,aAAa,GAAI,WAAW,MAAM,EAAE,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,KAAG,MAAM,CAA+D;IAE5J;;OAEG;IACH,MAAM,CAAC,aAAa,GAAI,YAAY,MAAM,KAAG,MAAM,GAAG,IAAI,CAaxD;IAEF;;OAEG;IACH,MAAM,CAAC,oBAAoB,GAAI,UAAU,MAAM,KAAG,MAAM,GAAG,IAAI,CAAgD;CAC/G"}

package/dist/apidoc/config.js

@@ -0,0 +1,254 @@
+import path from 'node:path';
+const getEnv = () => {
+    const prc = (process || {});
+    return prc.env;
+};
+/**
+ * Configuration for API Documentation Generator
+ */
+export class ApiDocConfig {
+    /** API metadata for OpenAPI info section */
+    static title = 'GoPass E-Shop API';
+    static version = '1.0.0';
+    static description = 'API documentation for the GoPass e-commerce platform';
+    static contact = {
+        name: 'GoPass Development Team',
+        email: 'dev@gopass.sk',
+    };
+    /** Server URLs for different environments */
+    static servers = {
+        development: {
+            url: 'http://localhost:5492',
+            description: 'Development server',
+        },
+        staging: {
+            url: 'https://staging.gopass.sk',
+            description: 'Staging server',
+        },
+        production: {
+            url: 'https://api.gopass.sk',
+            description: 'Production server',
+        },
+    };
+    /** Base paths for API routes */
+    static basePaths = {
+        shop: '/api/shop',
+        admin: '/api/admin',
+    };
+    /** Output directory paths (relative to server directory) */
+    static output = {
+        /** Base directory for generated documentation */
+        baseDir: 'src/apidoc',
+        /** Swagger UI output directory */
+        swaggerDir: 'src/apidoc/swagger',
+        /** HTML documentation output directory */
+        htmlDir: 'src/apidoc/default',
+        /** OpenAPI spec filename */
+        specFilename: 'openapi.json',
+    };
+    /** File patterns for controller discovery */
+    static patterns = {
+        /** Pattern to find controller files */
+        controllerFiles: '**/*Controller.ts',
+        /** Pattern to find router files */
+        routerFiles: '**/_router.ts',
+        /** Pattern to find service interface files */
+        serviceInterfaceFiles: '**/*.interface.ts',
+        /** Pattern to find args/dto files */
+        argsFiles: '**/args/*.ts',
+    };
+    /** Source directories (relative to server directory) */
+    static sourceDirectories = {
+        /** Shop API controllers directory */
+        shopApi: 'src/api/shop',
+        /** Admin API controllers directory */
+        adminApi: 'src/api/admin',
+        /** Services directory */
+        services: 'src/services',
+    };
+    /** HTTP method mappings from controller method names */
+    static httpMethodMappings = {
+        get: 'GET',
+        getAll: 'GET',
+        post: 'POST',
+        put: 'PUT',
+        patch: 'PATCH',
+        delete: 'DELETE',
+    };
+    /** Decorator names to look for */
+    static decorators = {
+        route: 'Route',
+        shopAuth: 'ShopApiAuth',
+        shopEnterpriseAuth: 'ShopApiEnterpriseAuth',
+        adminAuth: 'AdminApiAuth',
+        rateLimit: 'RequestRateLimit',
+        webMethod: 'WebMethod',
+    };
+    /** TypeScript types that need special handling in OpenAPI schema */
+    static specialTypes = {
+        'Temporal.PlainDateTime': {
+            type: 'string',
+            format: 'date-time',
+            description: 'ISO 8601 date-time string',
+        },
+        'Temporal.PlainDate': {
+            type: 'string',
+            format: 'date',
+            description: 'ISO 8601 date string',
+        },
+        'Temporal.PlainTime': {
+            type: 'string',
+            format: 'time',
+            description: 'ISO 8601 time string',
+        },
+        'Temporal.Instant': {
+            type: 'string',
+            format: 'date-time',
+            description: 'ISO 8601 instant string',
+        },
+        'Date': {
+            type: 'string',
+            format: 'date-time',
+            description: 'JavaScript Date object serialized as ISO 8601 string',
+        },
+        'Buffer': {
+            type: 'string',
+            format: 'binary',
+            description: 'Binary data',
+        },
+    };
+    /** Security scheme configuration for OpenAPI */
+    static securitySchemes = {
+        shopApiAuth: {
+            type: 'apiKey',
+            name: 'x-gp-apikey',
+            in: 'header',
+            description: 'API key passed via x-gp-apikey header for shop authentication',
+        },
+        bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+            description: 'JWT Bearer token authentication',
+        },
+    };
+    /** Tag descriptions for endpoint grouping */
+    static tagDescriptions = {
+        cart: 'Shopping cart operations',
+        auth: 'Authentication and authorization',
+        order: 'Order management',
+        product: 'Product catalog and search',
+        user: 'User profile and preferences',
+        payment: 'Payment processing',
+        delivery: 'Delivery options and shipping',
+        voucher: 'Voucher and discount codes',
+        content: 'CMS content and pages',
+        resort: 'Resort and location information',
+    };
+    /** Getting Started section content configuration */
+    static gettingStarted = {
+        /** Introduction paragraph shown after the lead description */
+        introText: `The GoPass API allows you to integrate your applications with our e-commerce platform.
+		You can use the API to manage shopping carts, process orders, handle user authentication,
+		and access product information.`,
+        /** API interfaces available (shown in URI structure table) */
+        apiInterfaces: [
+            { name: 'shop', description: 'Customer-facing shop API' },
+            { name: 'admin', description: 'Admin backoffice API' },
+        ],
+        /** Example resources for documentation */
+        exampleResources: [
+            'cart',
+            'auth',
+            'products',
+        ],
+        /** HTTP headers configuration */
+        httpHeaders: [
+            {
+                name: 'Content-Type',
+                description: 'Media type of the request body (required for POST/PUT)',
+                example: 'application/json',
+            },
+            {
+                name: 'Authorization',
+                description: 'Authentication token for protected endpoints (user sessions)',
+                example: 'Bearer {token}',
+            },
+            {
+                name: 'x-gp-apikey',
+                description: 'API key for enterprise-level operations and system integrations',
+                example: '{api-key}',
+            },
+            {
+                name: 'Accept-Language',
+                description: 'Preferred language for response content',
+                example: 'sk, en;q=0.8',
+            },
+        ],
+        /** Authentication methods configuration */
+        authentication: {
+            /** Bearer token authentication details */
+            bearerToken: {
+                title: 'Bearer Token (User Sessions)',
+                description: 'For user-facing operations, authenticate using a Bearer token:',
+                steps: [
+                    'Call the <code>/api/shop/auth/login</code> endpoint with valid credentials',
+                    'Use the returned token in subsequent requests',
+                    'Include the token in the <code>Authorization: Bearer {token}</code> header',
+                ],
+            },
+            /** API key authentication details */
+            apiKey: {
+                title: 'API Key (Enterprise Integrations)',
+                description: 'For enterprise-level operations and system integrations, use an API key:',
+                steps: [
+                    'Obtain an API key from the system administrator',
+                    'Include the key in the <code>x-gp-apikey: {api-key}</code> header',
+                ],
+                note: 'API keys are typically used for server-to-server communication, automated processes, and third-party integrations.',
+            },
+        },
+    };
+    /**
+     * Get the current environment mode
+     */
+    static getMode = () => getEnv().NODE_ENV || 'development';
+    /**
+     * Get the appropriate server URL based on current environment
+     */
+    static getCurrentServerUrl = () => {
+        const mode = ApiDocConfig.getMode();
+        if (mode === 'production') {
+            return ApiDocConfig.servers.production.url;
+        }
+        return ApiDocConfig.servers.development.url;
+    };
+    /**
+     * Get absolute path for output directory
+     */
+    static getOutputPath = (serverDir, type) => {
+        const outputDir = type === 'swagger' ? ApiDocConfig.output.swaggerDir : ApiDocConfig.output.htmlDir;
+        return path.join(serverDir, outputDir);
+    };
+    /**
+     * Get absolute path for source directory
+     */
+    static getSourcePath = (serverDir, type) => path.join(serverDir, ApiDocConfig.sourceDirectories[type]);
+    /**
+     * Get HTTP method from controller method name
+     */
+    static getHttpMethod = (methodName) => {
+        const lowerName = methodName.toLowerCase();
+        for (const [pattern, method,] of Object.entries(ApiDocConfig.httpMethodMappings)) {
+            if (lowerName === pattern.toLowerCase()) {
+                return method;
+            }
+        }
+        return null;
+    };
+    /**
+     * Get OpenAPI schema for special TypeScript types
+     */
+    static getSpecialTypeSchema = (typeName) => ApiDocConfig.specialTypes[typeName] || null;
+}
+//# sourceMappingURL=config.js.map

package/dist/apidoc/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/apidoc/config.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,MAAM,GAAG,GAAG,EAAE;IACnB,MAAM,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAQ,CAAC;IACnC,OAAO,GAAG,CAAC,GAAG,CAAC;AAChB,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,YAAY;IACxB,4CAA4C;IAC5C,MAAM,CAAU,KAAK,GAAG,mBAAmB,CAAC;IAC5C,MAAM,CAAU,OAAO,GAAG,OAAO,CAAC;IAClC,MAAM,CAAU,WAAW,GAAG,sDAAsD,CAAC;IACrF,MAAM,CAAU,OAAO,GAAG;QACzB,IAAI,EAAE,yBAAyB;QAC/B,KAAK,EAAE,eAAe;KACtB,CAAC;IAEF,6CAA6C;IAC7C,MAAM,CAAU,OAAO,GAAG;QACzB,WAAW,EAAE;YACZ,GAAG,EAAE,uBAAuB;YAC5B,WAAW,EAAE,oBAAoB;SACjC;QACD,OAAO,EAAE;YACR,GAAG,EAAE,2BAA2B;YAChC,WAAW,EAAE,gBAAgB;SAC7B;QACD,UAAU,EAAE;YACX,GAAG,EAAE,uBAAuB;YAC5B,WAAW,EAAE,mBAAmB;SAChC;KACD,CAAC;IAEF,gCAAgC;IAChC,MAAM,CAAU,SAAS,GAAG;QAC3B,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,YAAY;KACnB,CAAC;IAEF,4DAA4D;IAC5D,MAAM,CAAU,MAAM,GAAG;QACxB,iDAAiD;QACjD,OAAO,EAAE,YAAY;QACrB,kCAAkC;QAClC,UAAU,EAAE,oBAAoB;QAChC,0CAA0C;QAC1C,OAAO,EAAE,oBAAoB;QAC7B,4BAA4B;QAC5B,YAAY,EAAE,cAAc;KAC5B,CAAC;IAEF,6CAA6C;IAC7C,MAAM,CAAU,QAAQ,GAAG;QAC1B,uCAAuC;QACvC,eAAe,EAAE,mBAAmB;QACpC,mCAAmC;QACnC,WAAW,EAAE,eAAe;QAC5B,8CAA8C;QAC9C,qBAAqB,EAAE,mBAAmB;QAC1C,qCAAqC;QACrC,SAAS,EAAE,cAAc;KACzB,CAAC;IAEF,wDAAwD;IACxD,MAAM,CAAU,iBAAiB,GAAG;QACnC,qCAAqC;QACrC,OAAO,EAAE,cAAc;QACvB,sCAAsC;QACtC,QAAQ,EAAE,eAAe;QACzB,yBAAyB;QACzB,QAAQ,EAAE,cAAc;KACxB,CAAC;IAEF,wDAAwD;IACxD,MAAM,CAAU,kBAAkB,GAA2B;QAC5D,GAAG,EAAE,KAAK;QACV,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,MAAM;QACZ,GAAG,EAAE,KAAK;QACV,KAAK,EAAE,OAAO;QACd,MAAM,EAAE,QAAQ;KAChB,CAAC;IAEF,kCAAkC;IAClC,MAAM,CAAU,UAAU,GAAG;QAC5B,KAAK,EAAE,OAAO;QACd,QAAQ,EAAE,aAAa;QACvB,kBAAkB,EAAE,uBAAuB;QAC3C,SAAS,EAAE,cAAc;QACzB,SAAS,EAAE,kBAAkB;QAC7B,SAAS,EAAE,WAAW;KACtB,CAAC;IAEF,oEAAoE;IACpE,MAAM,CAAU,YAAY,GAA2B;QACtD,wBAAwB,EAAE;YACzB,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,WAAW;YACnB,WAAW,EAAE,2BAA2B;SACxC;QACD,oBAAoB,EAAE;YACrB,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,MAAM;YACd,WAAW,EAAE,sBAAsB;SACnC;QACD,oBAAoB,EAAE;YACrB,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,MAAM;YACd,WAAW,EAAE,sBAAsB;SACnC;QACD,kBAAkB,EAAE;YACnB,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,WAAW;YACnB,WAAW,EAAE,yBAAyB;SACtC;QACD,MAAM,EAAE;YACP,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,WAAW;YACnB,WAAW,EAAE,sDAAsD;SACnE;QACD,QAAQ,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,QAAQ;YAChB,WAAW,EAAE,aAAa;SAC1B;KACD,CAAC;IAEF,gDAAgD;IAChD,MAAM,CAAU,eAAe,GAAG;QACjC,WAAW,EAAE;YACZ,IAAI,EAAE,QAAiB;YACvB,IAAI,EAAE,aAAa;YACnB,EAAE,EAAE,QAAiB;YACrB,WAAW,EAAE,+DAA+D;SAC5E;QACD,UAAU,EAAE;YACX,IAAI,EAAE,MAAe;YACrB,MAAM,EAAE,QAAQ;YAChB,YAAY,EAAE,KAAK;YACnB,WAAW,EAAE,iCAAiC;SAC9C;KACD,CAAC;IAEF,6CAA6C;IAC7C,MAAM,CAAU,eAAe,GAA2B;QACzD,IAAI,EAAE,0BAA0B;QAChC,IAAI,EAAE,kCAAkC;QACxC,KAAK,EAAE,kBAAkB;QACzB,OAAO,EAAE,4BAA4B;QACrC,IAAI,EAAE,8BAA8B;QACpC,OAAO,EAAE,oBAAoB;QAC7B,QAAQ,EAAE,+BAA+B;QACzC,OAAO,EAAE,4BAA4B;QACrC,OAAO,EAAE,uBAAuB;QAChC,MAAM,EAAE,iCAAiC;KACzC,CAAC;IAEF,oDAAoD;IACpD,MAAM,CAAU,cAAc,GAAG;QAChC,8DAA8D;QAC9D,SAAS,EAAE;;kCAEqB;QAEhC,8DAA8D;QAC9D,aAAa,EAAE;YACd,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,0BAA0B,EAAE;YACzD,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE;SACtD;QAED,0CAA0C;QAC1C,gBAAgB,EAAE;YACjB,MAAM;YACN,MAAM;YACN,UAAU;SACV;QAED,iCAAiC;QACjC,WAAW,EAAE;YACZ;gBACC,IAAI,EAAE,cAAc;gBACpB,WAAW,EAAE,wDAAwD;gBACrE,OAAO,EAAE,kBAAkB;aAC3B;YACD;gBACC,IAAI,EAAE,eAAe;gBACrB,WAAW,EAAE,8DAA8D;gBAC3E,OAAO,EAAE,gBAAgB;aACzB;YACD;gBACC,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,iEAAiE;gBAC9E,OAAO,EAAE,WAAW;aACpB;YACD;gBACC,IAAI,EAAE,iBAAiB;gBACvB,WAAW,EAAE,yCAAyC;gBACtD,OAAO,EAAE,cAAc;aACvB;SACD;QAED,2CAA2C;QAC3C,cAAc,EAAE;YACf,0CAA0C;YAC1C,WAAW,EAAE;gBACZ,KAAK,EAAE,8BAA8B;gBACrC,WAAW,EAAE,gEAAgE;gBAC7E,KAAK,EAAE;oBACN,4EAA4E;oBAC5E,+CAA+C;oBAC/C,4EAA4E;iBAC5E;aACD;YACD,qCAAqC;YACrC,MAAM,EAAE;gBACP,KAAK,EAAE,mCAAmC;gBAC1C,WAAW,EAAE,0EAA0E;gBACvF,KAAK,EAAE;oBACN,iDAAiD;oBACjD,mEAAmE;iBACnE;gBACD,IAAI,EAAE,oHAAoH;aAC1H;SACD;KACD,CAAC;IAEF;;OAEG;IACH,MAAM,CAAC,OAAO,GAAG,GAAiC,EAAE,CAAE,MAAM,EAAE,CAAC,QAAyC,IAAI,aAAa,CAAC;IAE1H;;OAEG;IACH,MAAM,CAAC,mBAAmB,GAAG,GAAW,EAAE;QACzC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC;QAEpC,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;YAC3B,OAAO,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAC5C,CAAC;QAED,OAAO,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC;IAC7C,CAAC,CAAC;IAEF;;OAEG;IACH,MAAM,CAAC,aAAa,GAAG,CAAC,SAAiB,EAAE,IAAwB,EAAU,EAAE;QAC9E,MAAM,SAAS,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC;QAEpG,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACxC,CAAC,CAAC;IAEF;;OAEG;IACH,MAAM,CAAC,aAAa,GAAG,CAAC,SAAiB,EAAE,IAAyC,EAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;IAE5J;;OAEG;IACH,MAAM,CAAC,aAAa,GAAG,CAAC,UAAkB,EAAiB,EAAE;QAC5D,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;QAE3C,KAAK,MAAM,CACV,OAAO,EACP,MAAM,EACN,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACtD,IAAI,SAAS,KAAK,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;gBACzC,OAAO,MAAM,CAAC;YACf,CAAC;QACF,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC,CAAC;IAEF;;OAEG;IACH,MAAM,CAAC,oBAAoB,GAAG,CAAC,QAAgB,EAAiB,EAAE,CAAC,YAAY,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC"}

package/dist/apidoc/controller-parser.d.ts

@@ -0,0 +1,208 @@
+import type { MethodDeclaration, SourceFile } from 'ts-morph';
+import type { TypeResolver } from './type-resolver';
+/**
+ * Endpoint information with full path
+ */
+export interface EndpointInfo {
+    /** Controller class name */
+    className: string;
+    /** Route path from @Route decorator */
+    routePath: string;
+    /** Full API path including router hierarchy */
+    fullPath: string;
+    /** Full file path to controller */
+    filePath: string;
+    /** Tag for grouping */
+    tag: string;
+}
+/**
+ * Parsed authentication information from @ShopApiAuth decorator
+ */
+export interface AuthInfo {
+    /** Whether authentication decorator is present */
+    hasAuth: boolean;
+    /** Whether login is required */
+    requiresLogin: boolean;
+    /** Whether verified account is required */
+    requiresVerifiedAccount: boolean;
+    /** Whether this endpoint is enterprise-only (uses ShopApiEnterpriseAuth decorator) */
+    isEnterpriseOnly: boolean;
+}
+/**
+ * Information about a controller method (endpoint)
+ */
+export interface MethodInfo {
+    /** Method name (get, post, etc.) */
+    name: string;
+    /** HTTP method (GET, POST, etc.) */
+    httpMethod: string;
+    /** Authentication information */
+    auth: AuthInfo;
+    /** Request type name */
+    requestType: string | null;
+    /** Response type name */
+    responseType: string | null;
+    /** JSDoc description */
+    description: string | null;
+    /** Description extracted from service interface method JSDoc */
+    serviceDescription: string | null;
+    /** Description extracted from @param JSDoc tag for the request parameter */
+    paramDescription: string | null;
+    /** Extra parameter generator info (from @extraParameters JSDoc tag); when set, OpenAPI will include parameters from the named generator */
+    extraParameterGenerator: {
+        name: string;
+        args: (string | number)[];
+    } | null;
+}
+/**
+ * Parsed controller information
+ */
+export interface ControllerInfo {
+    /** Controller class name */
+    className: string;
+    /** Route path from @Route decorator */
+    routePath: string;
+    /** Full file path */
+    filePath: string;
+    /** Relative file path from server directory */
+    relativePath: string;
+    /** Methods in the controller */
+    methods: MethodInfo[];
+    /** Tag/group name derived from directory structure */
+    tag: string;
+}
+/**
+ * Mapping from controller method to service interface method
+ */
+export interface ServiceMethodMapping {
+    /** Service interface type name (e.g., "ICartService") */
+    interfaceType: string;
+    /** Import path to the service interface */
+    interfaceImportPath: string;
+    /** Service method name that is called (e.g., "validateCart") */
+    methodName: string;
+}
+/**
+ * Parser for TypeScript controller files using ts-morph
+ */
+export declare class ControllerParser {
+    private project;
+    private serverDir;
+    private routerCache;
+    private controllerPathCache;
+    private typeResolver;
+    constructor(serverDir: string);
+    /**
+     * Add a source file to the project by file path
+     * @param filePath The path to the TS source file
+     * @returns The added SourceFile object
+     */
+    addSourceFileAtPath(filePath: string): SourceFile;
+    /**
+     * Set the TypeResolver instance for extracting service method JSDoc
+     */
+    setTypeResolver(typeResolver: TypeResolver): void;
+    /**
+     * Parse endpoint info by controller class name
+     */
+    parseEndpoint(controllerClassName: string, apiType?: 'shopApi' | 'adminApi'): EndpointInfo | null;
+    /**
+     * Build cache of controller -> full path mappings by traversing router hierarchy
+     */
+    private buildControllerPathCache;
+    /**
+     * Recursively traverse router hierarchy and build controller path mappings
+     */
+    private traverseRouterHierarchy;
+    /**
+     * Parse a _router.ts file to extract router.use() and router.registerController() calls
+     */
+    private parseRouterFile;
+    /**
+     * Parse import statements from a source file
+     */
+    private parseImports;
+    /**
+     * Resolve a relative import path to an absolute file path
+     */
+    private resolveImportPath;
+    /**
+     * Normalize path by removing duplicate slashes and ensuring single leading slash
+     */
+    private normalizePath;
+    /**
+     * Discover all controller files in the shop API directory
+     */
+    discoverControllers(apiType?: 'shopApi' | 'adminApi'): string[];
+    /**
+     * Parse a single controller file
+     */
+    parseController(filePath: string): ControllerInfo | null;
+    /**
+     * Parse all controllers in the shop API
+     */
+    parseAllControllers(apiType?: 'shopApi' | 'adminApi'): ControllerInfo[];
+    /**
+     * Extract the route path from @Route decorator
+     */
+    private extractRouteDecorator;
+    /**
+     * Extract methods from a controller class
+     */
+    private extractMethods;
+    /**
+     * Extract authentication decorator information
+     */
+    private extractAuthDecorator;
+    /**
+     * Extract request and response types from method signature
+     */
+    private extractMethodTypes;
+    /**
+     * Extract JSDoc description from a method
+     */
+    private extractJsDocDescription;
+    /**
+     * Extract @param description from a method's JSDoc
+     * Returns the description of the first parameter (typically 'args')
+     */
+    private extractJsDocParams;
+    /**
+     * Extract service method mapping from a controller method
+     * Parses the method body to find container.get<InterfaceType>() and service.methodName() calls
+     */
+    extractServiceMethodMapping(method: MethodDeclaration, sourceFile: SourceFile): ServiceMethodMapping | null;
+    /**
+     * Extract string argument from decorator
+     */
+    private extractDecoratorStringArg;
+    /**
+     * Extract object argument from decorator
+     */
+    private extractDecoratorObjectArg;
+    /**
+     * Find files recursively matching a pattern
+     */
+    private findFilesRecursive;
+    /**
+     * Walk directory recursively
+     */
+    private walkDirectory;
+    /**
+     * Convert glob pattern to regex
+     */
+    private globToRegex;
+    /**
+     * Infer route from controller class name
+     */
+    private inferRouteFromClassName;
+    /**
+     * Extract tag from file path
+     */
+    private extractTagFromPath;
+    /**
+     * Clean type name by removing import paths and generics from common wrappers
+     */
+    private cleanTypeName;
+}
+//# sourceMappingURL=controller-parser.d.ts.map

package/dist/apidoc/controller-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-parser.d.ts","sourceRoot":"","sources":["../../src/apidoc/controller-parser.ts"],"names":[],"mappings":"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"}