@riktajs/swagger 0.1.0

package/dist/openapi/zod-to-openapi.js

@@ -0,0 +1,172 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+/**
+ * Type guard to check if a value is a Zod schema
+ * Uses duck typing to detect Zod schemas without requiring the full library
+ */
+export function isZodSchema(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '_def' in value &&
+        'safeParse' in value &&
+        typeof value.safeParse === 'function');
+}
+/**
+ * Convert JSON Schema 7 to OpenAPI 3.0 compatible schema
+ *
+ * Main differences:
+ * - OpenAPI uses `nullable: true` instead of `type: ['string', 'null']`
+ * - OpenAPI 3.0 doesn't support `$schema`, `$id`, etc.
+ * - Some JSON Schema features need to be simplified
+ */
+function jsonSchemaToOpenApi(jsonSchema) {
+    if (typeof jsonSchema === 'boolean') {
+        return jsonSchema ? {} : { not: {} };
+    }
+    const result = {};
+    const schema = jsonSchema;
+    // Handle type with null (convert to nullable)
+    if (Array.isArray(schema.type)) {
+        const types = schema.type;
+        const nullIndex = types.indexOf('null');
+        if (nullIndex !== -1) {
+            result.nullable = true;
+            const nonNullTypes = types.filter(t => t !== 'null');
+            if (nonNullTypes.length === 1) {
+                result.type = nonNullTypes[0];
+            }
+            else if (nonNullTypes.length > 1) {
+                // Multiple non-null types - use oneOf
+                result.oneOf = nonNullTypes.map(t => ({ type: t }));
+            }
+        }
+        else if (types.length === 1) {
+            result.type = types[0];
+        }
+    }
+    else if (schema.type) {
+        result.type = schema.type;
+    }
+    // Copy simple properties
+    const simpleProps = [
+        'format', 'description', 'default', 'example', 'enum',
+        'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum',
+        'minLength', 'maxLength', 'pattern',
+        'minItems', 'maxItems', 'uniqueItems',
+        'minProperties', 'maxProperties',
+        'required', 'readOnly', 'writeOnly', 'deprecated',
+    ];
+    for (const prop of simpleProps) {
+        if (schema[prop] !== undefined) {
+            result[prop] = schema[prop];
+        }
+    }
+    // Handle items (for arrays)
+    if (schema.items) {
+        if (Array.isArray(schema.items)) {
+            // Tuple - OpenAPI 3.0 doesn't support tuple validation well
+            result.items = { oneOf: schema.items.map(jsonSchemaToOpenApi) };
+        }
+        else {
+            result.items = jsonSchemaToOpenApi(schema.items);
+        }
+    }
+    // Handle properties (for objects)
+    if (schema.properties) {
+        result.properties = {};
+        for (const [key, value] of Object.entries(schema.properties)) {
+            result.properties[key] = jsonSchemaToOpenApi(value);
+        }
+    }
+    // Handle additionalProperties
+    if (schema.additionalProperties !== undefined) {
+        if (typeof schema.additionalProperties === 'boolean') {
+            result.additionalProperties = schema.additionalProperties;
+        }
+        else {
+            result.additionalProperties = jsonSchemaToOpenApi(schema.additionalProperties);
+        }
+    }
+    // Handle allOf, oneOf, anyOf
+    if (schema.allOf) {
+        result.allOf = schema.allOf.map(jsonSchemaToOpenApi);
+    }
+    if (schema.oneOf) {
+        result.oneOf = schema.oneOf.map(jsonSchemaToOpenApi);
+    }
+    if (schema.anyOf) {
+        result.anyOf = schema.anyOf.map(jsonSchemaToOpenApi);
+    }
+    // Handle not
+    if (schema.not) {
+        result.not = jsonSchemaToOpenApi(schema.not);
+    }
+    // Handle const (convert to enum with single value)
+    if (schema.const !== undefined) {
+        result.enum = [schema.const];
+    }
+    return result;
+}
+/**
+ * Convert a Zod schema to an OpenAPI 3.0 schema object
+ *
+ * Uses `zod-to-json-schema` for the heavy lifting, then converts
+ * JSON Schema 7 to OpenAPI 3.0 compatible format.
+ *
+ * Supports all Zod types including:
+ * - Primitives: string, number, boolean, bigint
+ * - Complex: object, array, tuple, record
+ * - Modifiers: optional, nullable, default
+ * - Validators: min, max, email, uuid, url, etc.
+ * - Enums: enum, nativeEnum
+ * - Unions and intersections
+ * - Literals
+ * - Effects (transform, refine)
+ *
+ * @param schema - The Zod schema to convert
+ * @returns OpenAPI schema object
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = z.object({
+ *   id: z.string().uuid(),
+ *   email: z.string().email(),
+ *   age: z.number().int().min(0).optional(),
+ * });
+ *
+ * const openApiSchema = zodToOpenApi(UserSchema);
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     id: { type: 'string', format: 'uuid' },
+ * //     email: { type: 'string', format: 'email' },
+ * //     age: { type: 'integer', minimum: 0 }
+ * //   },
+ * //   required: ['id', 'email']
+ * // }
+ * ```
+ */
+export function zodToOpenApi(schema) {
+    // Convert to JSON Schema using zod-to-json-schema
+    const jsonSchema = zodToJsonSchema(schema, {
+        target: 'openApi3',
+        $refStrategy: 'none', // Inline all references
+    });
+    // Convert JSON Schema to OpenAPI format
+    // The result from zodToJsonSchema may include $schema and definitions
+    // which are not part of JsonSchema7Type but are compatible
+    return jsonSchemaToOpenApi(jsonSchema);
+}
+/**
+ * Convert a Zod schema to OpenAPI schema, or pass through if already an OpenAPI schema
+ */
+export function toOpenApiSchema(schemaOrOpenApi) {
+    if (!schemaOrOpenApi) {
+        return undefined;
+    }
+    if (isZodSchema(schemaOrOpenApi)) {
+        return zodToOpenApi(schemaOrOpenApi);
+    }
+    // Already an OpenAPI schema object
+    return schemaOrOpenApi;
+}
+//# sourceMappingURL=zod-to-openapi.js.map

package/dist/openapi/zod-to-openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-openapi.js","sourceRoot":"","sources":["../../src/openapi/zod-to-openapi.ts"],"names":[],"mappings":"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"}

package/dist/plugin/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Swagger Plugin barrel export
+ *
+ * @packageDocumentation
+ */
+export { swaggerPlugin, registerSwagger, createSwaggerConfig, type SwaggerPluginOptions, } from './swagger.plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC"}

package/dist/plugin/index.js

@@ -0,0 +1,7 @@
+/**
+ * Swagger Plugin barrel export
+ *
+ * @packageDocumentation
+ */
+export { swaggerPlugin, registerSwagger, createSwaggerConfig, } from './swagger.plugin.js';
+//# sourceMappingURL=index.js.map

package/dist/plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,aAAa,EACb,eAAe,EACf,mBAAmB,GAEpB,MAAM,qBAAqB,CAAC"}

package/dist/plugin/swagger.plugin.d.ts

@@ -0,0 +1,157 @@
+import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import { type FastifySwaggerUiOptions } from '@fastify/swagger-ui';
+import type { SwaggerConfig, OpenApiDocument, OpenApiInfoObject } from '../types.js';
+type Constructor<T = unknown> = new (...args: any[]) => T;
+/**
+ * Swagger plugin options
+ */
+export interface SwaggerPluginOptions {
+    /**
+     * Swagger/OpenAPI configuration
+     */
+    config?: SwaggerConfig;
+    /**
+     * API Info (title, version, description, etc.)
+     * Can also be provided via config.info
+     */
+    info?: OpenApiInfoObject;
+    /**
+     * Controllers to document (optional - will auto-discover from registry if not provided)
+     */
+    controllers?: Constructor[];
+    /**
+     * Path to serve the OpenAPI JSON specification
+     * @default '/docs/json'
+     */
+    jsonPath?: string;
+    /**
+     * Path to serve the Swagger UI
+     * @default '/docs'
+     */
+    uiPath?: string;
+    /**
+     * Whether to expose the Swagger UI
+     * @default true
+     */
+    exposeUI?: boolean;
+    /**
+     * Whether to expose the OpenAPI JSON specification
+     * @default true
+     */
+    exposeSpec?: boolean;
+    /**
+     * Logo configuration for Swagger UI
+     */
+    logo?: {
+        url: string;
+        altText?: string;
+        backgroundColor?: string;
+    };
+    /**
+     * Swagger UI theme
+     * @default 'default'
+     */
+    theme?: 'default' | 'dark';
+    /**
+     * Transform the OpenAPI specification before serving
+     */
+    transform?: (spec: OpenApiDocument) => OpenApiDocument | Promise<OpenApiDocument>;
+}
+declare module 'fastify' {
+    interface FastifyInstance {
+        openApiSpec?: OpenApiDocument;
+    }
+}
+/**
+ * Swagger plugin for Fastify/Rikta
+ *
+ * Automatically generates OpenAPI documentation from Rikta controllers
+ * and serves Swagger UI for interactive API exploration.
+ *
+ * @example
+ * ```typescript
+ * import { RiktaFactory } from '@riktajs/core';
+ * import { swaggerPlugin } from '@riktajs/swagger';
+ *
+ * const app = await RiktaFactory.create();
+ *
+ * await app.register(swaggerPlugin, {
+ *   info: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *     description: 'API documentation for My App',
+ *   },
+ *   config: {
+ *     servers: [
+ *       { url: 'http://localhost:3000', description: 'Development' },
+ *     ],
+ *   },
+ * });
+ *
+ * // Swagger UI available at /docs
+ * // OpenAPI JSON at /docs/json
+ * ```
+ */
+export declare const swaggerPlugin: FastifyPluginAsync<SwaggerPluginOptions>;
+/**
+ * Register swagger plugin with a Rikta application
+ *
+ * Helper function that provides a simpler API for registering the plugin.
+ *
+ * @param app - Fastify instance
+ * @param options - Swagger plugin options
+ *
+ * @example
+ * ```typescript
+ * import { RiktaFactory } from '@riktajs/core';
+ * import { registerSwagger } from '@riktajs/swagger';
+ *
+ * const app = await RiktaFactory.create();
+ *
+ * await registerSwagger(app, {
+ *   info: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *   },
+ * });
+ * ```
+ */
+export declare function registerSwagger(app: FastifyInstance, options?: SwaggerPluginOptions): Promise<void>;
+/**
+ * Create a standalone Swagger configuration for manual use
+ *
+ * Use this when you need more control over the Swagger setup,
+ * or when integrating with an existing Fastify application.
+ *
+ * @param options - Swagger plugin options
+ * @returns Object containing swagger and swaggerUI options and specification
+ *
+ * @example
+ * ```typescript
+ * import fastify from 'fastify';
+ * import fastifySwagger from '@fastify/swagger';
+ * import fastifySwaggerUI from '@fastify/swagger-ui';
+ * import { createSwaggerConfig } from '@riktajs/swagger';
+ *
+ * const app = fastify();
+ * const { swaggerOptions, swaggerUIOptions, specification } = createSwaggerConfig({
+ *   info: { title: 'My API', version: '1.0.0' },
+ *   controllers: [UserController, ProductController],
+ * });
+ *
+ * await app.register(fastifySwagger, swaggerOptions);
+ * await app.register(fastifySwaggerUI, swaggerUIOptions);
+ * ```
+ */
+export declare function createSwaggerConfig(options?: SwaggerPluginOptions): {
+    swaggerOptions: {
+        mode: 'static';
+        specification: {
+            document: OpenApiDocument;
+        };
+    };
+    swaggerUIOptions: FastifySwaggerUiOptions;
+    specification: OpenApiDocument;
+};
+export {};
+//# sourceMappingURL=swagger.plugin.d.ts.map

package/dist/plugin/swagger.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger.plugin.d.ts","sourceRoot":"","sources":["../../src/plugin/swagger.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGnE,OAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAGrF,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAKrF,KAAK,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IAEvB;;;OAGG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IAEzB;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,IAAI,CAAC,EAAE;QACL,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAE3B;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACnF;AA4HD,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,WAAW,CAAC,EAAE,eAAe,CAAC;KAC/B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,aAAa,EAAE,kBAAkB,CAAC,oBAAoB,CAOlE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG;IACvE,cAAc,EAAE;QACd,IAAI,EAAE,QAAQ,CAAC;QACf,aAAa,EAAE;YAAE,QAAQ,EAAE,eAAe,CAAA;SAAE,CAAC;KAC9C,CAAC;IACF,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,aAAa,EAAE,eAAe,CAAC;CAChC,CA+CA"}

package/dist/plugin/swagger.plugin.js

@@ -0,0 +1,235 @@
+import fp from 'fastify-plugin';
+import fastifySwagger from '@fastify/swagger';
+import fastifySwaggerUI from '@fastify/swagger-ui';
+import { OpenApiGenerator } from '../openapi/generator.js';
+import { registry } from '@riktajs/core';
+/**
+ * Default plugin options
+ */
+const DEFAULT_OPTIONS = {
+    jsonPath: '/docs/json',
+    uiPath: '/docs',
+    exposeUI: true,
+    exposeSpec: true,
+};
+/**
+ * Swagger plugin implementation
+ *
+ * Registers @fastify/swagger and @fastify/swagger-ui with automatic
+ * OpenAPI specification generation from Rikta controllers.
+ */
+async function swaggerPluginImpl(fastify, options) {
+    const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
+    const { jsonPath, uiPath, exposeUI, exposeSpec, controllers, config, info, transform } = mergedOptions;
+    // Build info object from options or config
+    const apiInfo = info || config?.info || {
+        title: 'API Documentation',
+        version: '1.0.0',
+    };
+    // Create OpenAPI generator
+    const generator = new OpenApiGenerator({
+        ...config,
+        info: apiInfo,
+    });
+    // Get controllers to document
+    const controllersToDocument = controllers || registry.getControllers();
+    // Add controllers to generator
+    for (const controller of controllersToDocument) {
+        generator.addController(controller);
+    }
+    // Add security schemes from config
+    if (config?.securitySchemes) {
+        for (const [name, scheme] of Object.entries(config.securitySchemes)) {
+            generator.addSecurityScheme(name, scheme);
+        }
+    }
+    // Generate OpenAPI specification
+    let spec = generator.generate();
+    // Apply transform if provided
+    if (transform) {
+        spec = await transform(spec);
+    }
+    // Register @fastify/swagger with static specification
+    await fastify.register(fastifySwagger, {
+        mode: 'static',
+        specification: {
+            document: spec, // Type assertion needed due to fastify-swagger types
+        },
+    });
+    // Register @fastify/swagger-ui if enabled
+    if (exposeUI) {
+        const uiOptions = {
+            routePrefix: uiPath,
+            uiConfig: {
+                docExpansion: 'list',
+                deepLinking: true,
+                displayRequestDuration: true,
+                filter: true,
+                syntaxHighlight: {
+                    activate: true,
+                    theme: mergedOptions.theme === 'dark' ? 'monokai' : 'agate',
+                },
+            },
+            staticCSP: true,
+            transformStaticCSP: (header) => header,
+        };
+        // Add logo if provided
+        if (mergedOptions.logo) {
+            uiOptions.logo = {
+                type: 'image/png',
+                content: mergedOptions.logo.url,
+                href: mergedOptions.logo.url,
+            };
+        }
+        await fastify.register(fastifySwaggerUI, uiOptions);
+    }
+    // Add JSON spec route if enabled
+    // @fastify/swagger-ui registers routes at {uiPath}/json when UI is enabled
+    // So we only add custom route if:
+    // 1. UI is disabled (no swagger-ui default route exists)
+    // 2. jsonPath differs from swagger-ui default path
+    const defaultSwaggerUIJsonPath = `${uiPath}/json`;
+    const shouldRegisterCustomJsonRoute = exposeSpec && (!exposeUI ||
+        (jsonPath !== defaultSwaggerUIJsonPath && jsonPath !== '/docs/json'));
+    if (shouldRegisterCustomJsonRoute) {
+        fastify.get(jsonPath, {
+            schema: {
+                hide: true,
+            },
+        }, async () => {
+            return spec;
+        });
+    }
+    // Store spec on fastify instance for later access
+    fastify.decorate('openApiSpec', spec);
+}
+/**
+ * Swagger plugin for Fastify/Rikta
+ *
+ * Automatically generates OpenAPI documentation from Rikta controllers
+ * and serves Swagger UI for interactive API exploration.
+ *
+ * @example
+ * ```typescript
+ * import { RiktaFactory } from '@riktajs/core';
+ * import { swaggerPlugin } from '@riktajs/swagger';
+ *
+ * const app = await RiktaFactory.create();
+ *
+ * await app.register(swaggerPlugin, {
+ *   info: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *     description: 'API documentation for My App',
+ *   },
+ *   config: {
+ *     servers: [
+ *       { url: 'http://localhost:3000', description: 'Development' },
+ *     ],
+ *   },
+ * });
+ *
+ * // Swagger UI available at /docs
+ * // OpenAPI JSON at /docs/json
+ * ```
+ */
+export const swaggerPlugin = fp(swaggerPluginImpl, {
+    fastify: '>=4.0.0',
+    name: '@riktajs/swagger',
+    dependencies: [],
+});
+/**
+ * Register swagger plugin with a Rikta application
+ *
+ * Helper function that provides a simpler API for registering the plugin.
+ *
+ * @param app - Fastify instance
+ * @param options - Swagger plugin options
+ *
+ * @example
+ * ```typescript
+ * import { RiktaFactory } from '@riktajs/core';
+ * import { registerSwagger } from '@riktajs/swagger';
+ *
+ * const app = await RiktaFactory.create();
+ *
+ * await registerSwagger(app, {
+ *   info: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *   },
+ * });
+ * ```
+ */
+export async function registerSwagger(app, options = {}) {
+    await app.register(swaggerPlugin, options);
+}
+/**
+ * Create a standalone Swagger configuration for manual use
+ *
+ * Use this when you need more control over the Swagger setup,
+ * or when integrating with an existing Fastify application.
+ *
+ * @param options - Swagger plugin options
+ * @returns Object containing swagger and swaggerUI options and specification
+ *
+ * @example
+ * ```typescript
+ * import fastify from 'fastify';
+ * import fastifySwagger from '@fastify/swagger';
+ * import fastifySwaggerUI from '@fastify/swagger-ui';
+ * import { createSwaggerConfig } from '@riktajs/swagger';
+ *
+ * const app = fastify();
+ * const { swaggerOptions, swaggerUIOptions, specification } = createSwaggerConfig({
+ *   info: { title: 'My API', version: '1.0.0' },
+ *   controllers: [UserController, ProductController],
+ * });
+ *
+ * await app.register(fastifySwagger, swaggerOptions);
+ * await app.register(fastifySwaggerUI, swaggerUIOptions);
+ * ```
+ */
+export function createSwaggerConfig(options = {}) {
+    const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
+    const { uiPath, controllers, config, info } = mergedOptions;
+    // Build info object
+    const apiInfo = info || config?.info || {
+        title: 'API Documentation',
+        version: '1.0.0',
+    };
+    // Create generator
+    const generator = new OpenApiGenerator({
+        ...config,
+        info: apiInfo,
+    });
+    // Add controllers
+    const controllersToDocument = controllers || registry.getControllers();
+    for (const controller of controllersToDocument) {
+        generator.addController(controller);
+    }
+    // Add security schemes
+    if (config?.securitySchemes) {
+        for (const [name, scheme] of Object.entries(config.securitySchemes)) {
+            generator.addSecurityScheme(name, scheme);
+        }
+    }
+    const specification = generator.generate();
+    return {
+        swaggerOptions: {
+            mode: 'static',
+            specification: { document: specification },
+        },
+        swaggerUIOptions: {
+            routePrefix: uiPath,
+            uiConfig: {
+                docExpansion: 'list',
+                deepLinking: true,
+                displayRequestDuration: true,
+                filter: true,
+            },
+        },
+        specification,
+    };
+}
+//# sourceMappingURL=swagger.plugin.js.map

package/dist/plugin/swagger.plugin.js.map

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