@classytic/arc 1.0.0

package/dist/docs/index.js

@@ -0,0 +1,650 @@
+import fp from 'fastify-plugin';
+
+// src/docs/openapi.ts
+
+// src/registry/ResourceRegistry.ts
+var ResourceRegistry = class {
+  _resources;
+  _frozen;
+  constructor() {
+    this._resources = /* @__PURE__ */ new Map();
+    this._frozen = false;
+  }
+  /**
+   * Register a resource
+   */
+  register(resource, options = {}) {
+    if (this._frozen) {
+      throw new Error(
+        `Registry frozen. Cannot register '${resource.name}' after startup.`
+      );
+    }
+    if (this._resources.has(resource.name)) {
+      throw new Error(`Resource '${resource.name}' already registered.`);
+    }
+    const entry = {
+      name: resource.name,
+      displayName: resource.displayName,
+      tag: resource.tag,
+      prefix: resource.prefix,
+      module: options.module ?? void 0,
+      adapter: resource.adapter ? {
+        type: resource.adapter.type,
+        name: resource.adapter.name
+      } : null,
+      permissions: resource.permissions,
+      presets: resource._appliedPresets ?? [],
+      routes: [],
+      // Populated later by getIntrospection()
+      additionalRoutes: resource.additionalRoutes.map((r) => ({
+        method: r.method,
+        path: r.path,
+        handler: typeof r.handler === "string" ? r.handler : r.handler.name || "anonymous",
+        summary: r.summary,
+        description: r.description,
+        permissions: r.permissions,
+        wrapHandler: r.wrapHandler,
+        schema: r.schema
+        // Include schema for OpenAPI docs
+      })),
+      events: Object.keys(resource.events ?? {}),
+      registeredAt: (/* @__PURE__ */ new Date()).toISOString(),
+      disableDefaultRoutes: resource.disableDefaultRoutes,
+      openApiSchemas: options.openApiSchemas,
+      plugin: resource.toPlugin()
+      // Store plugin factory
+    };
+    this._resources.set(resource.name, entry);
+    return this;
+  }
+  /**
+   * Get resource by name
+   */
+  get(name) {
+    return this._resources.get(name);
+  }
+  /**
+   * Get all resources
+   */
+  getAll() {
+    return Array.from(this._resources.values());
+  }
+  /**
+   * Get resources by module
+   */
+  getByModule(moduleName) {
+    return this.getAll().filter((r) => r.module === moduleName);
+  }
+  /**
+   * Get resources by preset
+   */
+  getByPreset(presetName) {
+    return this.getAll().filter((r) => r.presets.includes(presetName));
+  }
+  /**
+   * Check if resource exists
+   */
+  has(name) {
+    return this._resources.has(name);
+  }
+  /**
+   * Get registry statistics
+   */
+  getStats() {
+    const resources = this.getAll();
+    const presetCounts = {};
+    for (const r of resources) {
+      for (const preset of r.presets) {
+        presetCounts[preset] = (presetCounts[preset] ?? 0) + 1;
+      }
+    }
+    return {
+      totalResources: resources.length,
+      byModule: this._groupBy(resources, "module"),
+      presetUsage: presetCounts,
+      totalRoutes: resources.reduce((sum, r) => {
+        const defaultRouteCount = r.disableDefaultRoutes ? 0 : 5;
+        return sum + (r.additionalRoutes?.length ?? 0) + defaultRouteCount;
+      }, 0),
+      totalEvents: resources.reduce((sum, r) => sum + (r.events?.length ?? 0), 0)
+    };
+  }
+  /**
+   * Get full introspection data
+   */
+  getIntrospection() {
+    return {
+      resources: this.getAll().map((r) => {
+        const defaultRoutes = r.disableDefaultRoutes ? [] : [
+          { method: "GET", path: r.prefix, operation: "list" },
+          { method: "GET", path: `${r.prefix}/:id`, operation: "get" },
+          { method: "POST", path: r.prefix, operation: "create" },
+          { method: "PATCH", path: `${r.prefix}/:id`, operation: "update" },
+          { method: "DELETE", path: `${r.prefix}/:id`, operation: "delete" }
+        ];
+        return {
+          name: r.name,
+          displayName: r.displayName,
+          prefix: r.prefix,
+          module: r.module,
+          presets: r.presets,
+          permissions: r.permissions,
+          routes: [
+            ...defaultRoutes,
+            ...r.additionalRoutes?.map((ar) => ({
+              method: ar.method,
+              path: `${r.prefix}${ar.path}`,
+              operation: typeof ar.handler === "string" ? ar.handler : "custom",
+              handler: typeof ar.handler === "string" ? ar.handler : void 0,
+              summary: ar.summary
+            })) ?? []
+          ],
+          events: r.events
+        };
+      }),
+      stats: this.getStats(),
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Freeze registry (prevent further registrations)
+   */
+  freeze() {
+    this._frozen = true;
+  }
+  /**
+   * Check if frozen
+   */
+  isFrozen() {
+    return this._frozen;
+  }
+  /**
+   * Unfreeze registry (for testing)
+   */
+  _unfreeze() {
+    this._frozen = false;
+  }
+  /**
+   * Clear all resources (for testing)
+   */
+  _clear() {
+    this._resources.clear();
+    this._frozen = false;
+  }
+  /**
+   * Group by key
+   */
+  _groupBy(arr, key) {
+    const result = {};
+    for (const item of arr) {
+      const k = String(item[key] ?? "uncategorized");
+      result[k] = (result[k] ?? 0) + 1;
+    }
+    return result;
+  }
+};
+var registryKey = /* @__PURE__ */ Symbol.for("arc.resourceRegistry");
+var globalScope = globalThis;
+var resourceRegistry = globalScope[registryKey] ?? new ResourceRegistry();
+if (!globalScope[registryKey]) {
+  globalScope[registryKey] = resourceRegistry;
+}
+
+// src/docs/openapi.ts
+var openApiPlugin = async (fastify, opts = {}) => {
+  const {
+    title = "Arc API",
+    version = "1.0.0",
+    description,
+    serverUrl,
+    prefix = "/_docs",
+    apiPrefix = "",
+    authRoles = []
+  } = opts;
+  const buildSpec = () => {
+    const resources = resourceRegistry.getAll();
+    const paths = {};
+    const tags = [];
+    for (const resource of resources) {
+      tags.push({
+        name: resource.tag || resource.name,
+        description: `${resource.displayName || resource.name} operations`
+      });
+      const resourcePaths = generateResourcePaths(resource, apiPrefix);
+      Object.assign(paths, resourcePaths);
+    }
+    return {
+      openapi: "3.0.3",
+      info: {
+        title,
+        version,
+        ...description && { description }
+      },
+      ...serverUrl && {
+        servers: [{ url: serverUrl }]
+      },
+      paths,
+      components: {
+        schemas: generateSchemas(resources),
+        securitySchemes: {
+          bearerAuth: {
+            type: "http",
+            scheme: "bearer",
+            bearerFormat: "JWT"
+          },
+          orgHeader: {
+            type: "apiKey",
+            in: "header",
+            name: "x-organization-id"
+          }
+        }
+      },
+      tags
+      // Note: Security is defined per-operation, not globally
+      // This allows public routes to have no security requirement
+    };
+  };
+  fastify.get(`${prefix}/openapi.json`, async (request, reply) => {
+    if (authRoles.length > 0) {
+      const user = request.user;
+      const hasRole = authRoles.some((role) => user?.roles?.includes(role));
+      if (!hasRole && !user?.roles?.includes("superadmin")) {
+        reply.code(403).send({ error: "Access denied" });
+        return;
+      }
+    }
+    const spec = buildSpec();
+    return spec;
+  });
+  fastify.log?.info?.(`OpenAPI spec available at ${prefix}/openapi.json`);
+};
+function toOpenApiPath(path) {
+  return path.replace(/:([^/]+)/g, "{$1}");
+}
+function convertSchemaToParameters(schema) {
+  const params = [];
+  const properties = schema.properties || {};
+  const required = schema.required || [];
+  for (const [name, prop] of Object.entries(properties)) {
+    const description = prop.description;
+    const { description: _, ...schemaProps } = prop;
+    const param = {
+      name,
+      in: "query",
+      required: required.includes(name),
+      schema: schemaProps
+    };
+    if (description) {
+      param.description = description;
+    }
+    params.push(param);
+  }
+  return params;
+}
+var DEFAULT_LIST_PARAMS = [
+  { name: "page", in: "query", schema: { type: "integer" }, description: "Page number" },
+  { name: "limit", in: "query", schema: { type: "integer" }, description: "Items per page" },
+  { name: "sort", in: "query", schema: { type: "string" }, description: "Sort field (prefix with - for descending)" }
+];
+function generateResourcePaths(resource, apiPrefix = "") {
+  const paths = {};
+  const basePath = `${apiPrefix}${resource.prefix}`;
+  if (resource.disableDefaultRoutes && (!resource.additionalRoutes || resource.additionalRoutes.length === 0)) {
+    return paths;
+  }
+  if (!resource.disableDefaultRoutes) {
+    const listParams = resource.openApiSchemas?.listQuery ? convertSchemaToParameters(resource.openApiSchemas.listQuery) : DEFAULT_LIST_PARAMS;
+    paths[basePath] = {
+      get: createOperation(resource, "list", "List all", {
+        parameters: listParams,
+        responses: {
+          "200": {
+            description: "List of items",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean" },
+                    data: { type: "array", items: { $ref: `#/components/schemas/${resource.name}` } },
+                    pagination: { $ref: "#/components/schemas/Pagination" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }),
+      post: createOperation(resource, "create", "Create new", {
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: { $ref: `#/components/schemas/${resource.name}Input` }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "Created successfully",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean" },
+                    data: { $ref: `#/components/schemas/${resource.name}` },
+                    message: { type: "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      })
+    };
+    paths[toOpenApiPath(`${basePath}/:id`)] = {
+      get: createOperation(resource, "get", "Get by ID", {
+        parameters: [
+          { name: "id", in: "path", required: true, schema: { type: "string" } }
+        ],
+        responses: {
+          "200": {
+            description: "Item found",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean" },
+                    data: { $ref: `#/components/schemas/${resource.name}` }
+                  }
+                }
+              }
+            }
+          },
+          "404": { description: "Not found" }
+        }
+      }),
+      patch: createOperation(resource, "update", "Update", {
+        parameters: [
+          { name: "id", in: "path", required: true, schema: { type: "string" } }
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: { $ref: `#/components/schemas/${resource.name}Input` }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Updated successfully",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean" },
+                    data: { $ref: `#/components/schemas/${resource.name}` },
+                    message: { type: "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }),
+      delete: createOperation(resource, "delete", "Delete", {
+        parameters: [
+          { name: "id", in: "path", required: true, schema: { type: "string" } }
+        ],
+        responses: {
+          "200": {
+            description: "Deleted successfully",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean" },
+                    message: { type: "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      })
+    };
+  }
+  for (const route of resource.additionalRoutes || []) {
+    const fullPath = toOpenApiPath(`${basePath}${route.path}`);
+    const method = route.method.toLowerCase();
+    if (!paths[fullPath]) {
+      paths[fullPath] = {};
+    }
+    const handlerName = typeof route.handler === "string" ? route.handler : "handler";
+    const isPublicRoute = route.permissions?._isPublic === true;
+    const requiresAuthForRoute = !!route.permissions && !isPublicRoute;
+    const extras = {
+      parameters: extractPathParams(route.path),
+      responses: {
+        "200": { description: route.description || "Success" }
+      }
+    };
+    const routeSchema = route.schema;
+    if (routeSchema?.body && ["post", "put", "patch"].includes(method)) {
+      extras.requestBody = {
+        required: true,
+        content: {
+          "application/json": {
+            schema: routeSchema.body
+          }
+        }
+      };
+    }
+    if (routeSchema?.querystring) {
+      const queryParams = convertSchemaToParameters(routeSchema.querystring);
+      extras.parameters = [...extras.parameters || [], ...queryParams];
+    }
+    if (routeSchema?.response) {
+      const responseSchemas = routeSchema.response;
+      for (const [statusCode, schema] of Object.entries(responseSchemas)) {
+        extras.responses[statusCode] = {
+          description: schema.description || `Response ${statusCode}`,
+          content: {
+            "application/json": {
+              schema
+            }
+          }
+        };
+      }
+    }
+    paths[fullPath][method] = createOperation(
+      resource,
+      handlerName,
+      route.summary ?? handlerName,
+      extras,
+      requiresAuthForRoute
+    );
+  }
+  return paths;
+}
+function createOperation(resource, operation, summary, extras, requiresAuthOverride) {
+  const permissions = resource.permissions || {};
+  const operationPermission = permissions[operation];
+  const isPublic = operationPermission?._isPublic === true;
+  const requiresAuth = requiresAuthOverride !== void 0 ? requiresAuthOverride : typeof operationPermission === "function" && !isPublic;
+  return {
+    tags: [resource.tag || "Resource"],
+    summary: `${summary} ${(resource.displayName || resource.name).toLowerCase()}`,
+    operationId: `${resource.name}_${operation}`,
+    // Only add security requirement if route requires auth
+    ...requiresAuth && {
+      security: [{ bearerAuth: [] }]
+    },
+    responses: {
+      ...requiresAuth && {
+        "401": { description: "Unauthorized" },
+        "403": { description: "Forbidden" }
+      },
+      "500": { description: "Internal server error" }
+    },
+    ...extras
+  };
+}
+function extractPathParams(path) {
+  const params = [];
+  const matches = path.matchAll(/:([^/]+)/g);
+  for (const match of matches) {
+    const paramName = match[1];
+    if (paramName) {
+      params.push({
+        name: paramName,
+        in: "path",
+        required: true,
+        schema: { type: "string" }
+      });
+    }
+  }
+  return params;
+}
+function generateSchemas(resources) {
+  const schemas = {
+    // Common schemas
+    Pagination: {
+      type: "object",
+      properties: {
+        page: { type: "integer" },
+        limit: { type: "integer" },
+        total: { type: "integer" },
+        totalPages: { type: "integer" },
+        hasNextPage: { type: "boolean" },
+        hasPrevPage: { type: "boolean" }
+      }
+    },
+    Error: {
+      type: "object",
+      properties: {
+        success: { type: "boolean", example: false },
+        error: { type: "string" },
+        code: { type: "string" },
+        requestId: { type: "string" },
+        timestamp: { type: "string" }
+      }
+    }
+  };
+  for (const resource of resources) {
+    const storedSchemas = resource.openApiSchemas;
+    if (storedSchemas?.createBody) {
+      schemas[resource.name] = {
+        type: "object",
+        description: resource.displayName,
+        ...storedSchemas.createBody,
+        properties: {
+          _id: { type: "string", description: "Unique identifier" },
+          ...storedSchemas.createBody.properties ?? {},
+          createdAt: { type: "string", format: "date-time", description: "Creation timestamp" },
+          updatedAt: { type: "string", format: "date-time", description: "Last update timestamp" }
+        }
+      };
+      schemas[`${resource.name}Input`] = {
+        type: "object",
+        description: `${resource.displayName} create input`,
+        ...storedSchemas.createBody
+      };
+      if (storedSchemas.updateBody) {
+        schemas[`${resource.name}Update`] = {
+          type: "object",
+          description: `${resource.displayName} update input`,
+          ...storedSchemas.updateBody
+        };
+      }
+    } else {
+      schemas[resource.name] = {
+        type: "object",
+        description: resource.displayName,
+        properties: {
+          _id: { type: "string", description: "Unique identifier" },
+          createdAt: { type: "string", format: "date-time", description: "Creation timestamp" },
+          updatedAt: { type: "string", format: "date-time", description: "Last update timestamp" }
+        }
+      };
+      schemas[`${resource.name}Input`] = {
+        type: "object",
+        description: `${resource.displayName} input`
+      };
+    }
+  }
+  return schemas;
+}
+var openapi_default = fp(openApiPlugin, {
+  name: "arc-openapi",
+  fastify: "5.x"
+});
+var scalarPlugin = async (fastify, opts = {}) => {
+  const {
+    routePrefix = "/docs",
+    specUrl = "/_docs/openapi.json",
+    title = "API Documentation",
+    theme = "default",
+    showSidebar = true,
+    darkMode = false,
+    authRoles = [],
+    customCss = "",
+    favicon
+  } = opts;
+  const scalarConfig = JSON.stringify({
+    spec: { url: specUrl },
+    theme,
+    showSidebar,
+    darkMode,
+    ...favicon && { favicon }
+  });
+  const html = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${title}</title>
+  ${favicon ? `<link rel="icon" href="${favicon}">` : ""}
+  <style>
+    body { margin: 0; padding: 0; }
+    ${customCss}
+  </style>
+</head>
+<body>
+  <script id="api-reference" data-url="${specUrl}"></script>
+  <script>
+    var configuration = ${scalarConfig};
+    document.getElementById('api-reference').dataset.configuration = JSON.stringify(configuration);
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+  fastify.get(routePrefix, async (request, reply) => {
+    if (authRoles.length > 0) {
+      const user = request.user;
+      const hasRole = authRoles.some((role) => user?.roles?.includes(role));
+      if (!hasRole && !user?.roles?.includes("superadmin")) {
+        reply.code(403).send({ error: "Access denied" });
+        return;
+      }
+    }
+    reply.type("text/html").send(html);
+  });
+  if (!routePrefix.endsWith("/")) {
+    fastify.get(`${routePrefix}/`, async (_, reply) => {
+      reply.redirect(routePrefix);
+    });
+  }
+  fastify.log?.info?.(`Scalar API docs available at ${routePrefix}`);
+};
+var scalar_default = fp(scalarPlugin, {
+  name: "arc-scalar",
+  fastify: "5.x"
+});
+
+export { openapi_default as openApiPlugin, openApiPlugin as openApiPluginFn, scalar_default as scalarPlugin, scalarPlugin as scalarPluginFn };