npm - azurajs-scalar - Versions diffs - 1.0.0 - Mend

azurajs-scalar 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,43 @@
+MIT License
+Copyright (c) 2026 Eduardo Developer <https://github.com/D3vEduardo>
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+---
+## Contribution Guidelines
+Contributions to this library are welcome! You can contribute by forking this repository and submitting a pull request.
+**Important Notes:**
+- All contributions are subject to review and acceptance by the project maintainer
+- Submitting a pull request does not grant contributor copyright or ownership rights to the library
+- The original copyright and ownership remains with Eduardo Developer
+- Contributors are acknowledged in good faith, but do not receive legal ownership or copyright claims
+- By contributing, you agree that your contributions become part of the library under the same MIT License
+**How to Contribute:**
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+5. Please read this license carefully before contributing
+For more information about this license, please refer to the full license text above.

package/README.md ADDED Viewed

@@ -0,0 +1,212 @@
+# @azurajs/scalar 📘
+> Proxy middleware and controller to scalar documentation. 🔗
+---
+## 🚀 Features
+- ⚡ Fast and lightweight proxy middleware
+- 🎨 Customizable HTML templates
+- 🌐 Seamless integration with Scalar API references
+- 🔧 Easy configuration and setup
+---
+## 📦 Installation
+Choose your favorite package manager:
+### npm
+```bash
+npm i @azurajs/scalar
+```
+### pnpm
+```bash
+pnpm i @azurajs/scalar
+```
+---
+## 🛠️ Usage
+### Configuration
+#### src/index.ts
+```ts
+import { AzuraClient } from "azurajs";
+import { Scalar } from "@azurajs/scalar";
+import path from "path";
+import { fileURLToPath } from "url";
+import { applyDecorators } from "azurajs/decorators";
+import * from "./controllers"
+const app = new AzuraClient();
+const __filename = fileURLToPath(import.meta.url); // Optional
+const __dirname = path.dirname(__filename); // Optional
+const scalar = new Scalar({
+  apiSpecUrl: "http://localhost:4002/api-spec.json",
+  proxyUrl: "http://localhost:4002",
+  customHtmlPath: path.join(__dirname, "./public/html/api-docs.html"), // Optional
+});
+applyDecorators(app, Object.values(Controllers))
+```
+### Controller Setup
+#### src/controllers/docs.controller.ts
+```ts
+import { Controller, Get, Res } from "azurajs/decorators";
+import { ResponseServer } from "azurajs/types";
+import { getScalarDocs } from "@azurajs/scalar";
+@Controller("/docs")
+export class DocsController {
+  @Get("/")
+  scalarDocs(@Res() res: ResponseServer) {
+    getScalarDocs(res);
+  }
+}
+```
+### Export Controllers
+#### src/controllers/index.ts
+```ts
+export * from "./docs.controller.ts";
+```
+---
+## 🎨 Custom HTML Template
+Create a custom HTML template for your API documentation with full control over styling and layout.
+### Example:
+```html
+<!doctype html>
+<html>
+  <head>
+    <title>Versum API - Sistine Chapel Theme</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Cinzel:wght@400;700&family=Libre+Baskerville:ital,wght@0,400;0,700;1,400&display=swap"
+      rel="stylesheet"
+    />
+    <style>
+      :root {
+        --scalar-font: "Libre Baskerville", serif;
+        --scalar-font-code: "Courier New", monospace;
+      }
+      .light-mode {
+        --scalar-color-1: #2b2b26;
+        --scalar-color-2: #5f5a4f;
+        --scalar-color-accent: #8b3f2f;
+        --scalar-background-1: #f8f3ea;
+        --scalar-background-2: #efe6d6;
+        --scalar-background-3: #e3d7c3;
+        --scalar-border-color: rgba(139, 63, 47, 0.18);
+      }
+      .dark-mode {
+        --scalar-color-1: #f3eadb;
+        --scalar-color-2: #d6c7a1;
+        --scalar-color-accent: #b86b2f;
+        --scalar-background-1: #1c170f;
+        --scalar-background-2: #241e14;
+        --scalar-background-3: #2e2619;
+        --scalar-border-color: rgba(184, 107, 47, 0.25);
+      }
+      h1,
+      h2,
+      h3 {
+        font-family: "Cinzel", serif;
+        font-weight: 700;
+        color: var(--scalar-color-accent) !important;
+        letter-spacing: 0.5px;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app">Carregando...</div>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+    <script>
+      // Busca o spec da porta 4002
+      fetch("&{api_spec_url}")
+        .then((res) => {
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          return res.json();
+        })
+        .then((spec) => {
+          console.log("Spec carregado:", spec);
+          Scalar.createApiReference("#app", {
+            spec: {
+              content: spec,
+            },
+            proxy: "&{proxy_url}",
+            theme: "none",
+            showSidebar: true,
+            withDefaultFonts: false,
+          });
+        })
+        .catch((err) => {
+          console.error("Erro ao carregar spec:", err);
+          document.getElementById("app").innerHTML =
+            `<pre style="color: red; padding: 20px;">
+Erro ao carregar API spec: ${err.message}
+Verifique se a API está rodando em &{proxy_url}
+            </pre>`;
+        });
+    </script>
+  </body>
+</html>
+```
+### 🔧 External Variables
+- `&{proxy_url}` - The proxy URL configured in your [configuration](####src/index.ts)
+- `&{api_spec_url}` - The API specification URL configured in your [configuration](####src/index.ts)
+---
+## 🌐 References
+- [AzuraJS](https://github.com/azurajs/azura) - The framework this package integrates with
+- [Scalar](https://scalar.com/products/api-references/integrations/html-js) - The API reference tool
+---
+## 👨‍💻 Author
+**Eduardo Developer**
+[![GitHub Profile](https://img.shields.io/badge/GitHub-D3vEduardo-blue?logo=github)](https://github.com/D3vEduardo)
+---
+## 📄 License
+This project is licensed under the [MIT License](./LICENSE) - see the LICENSE file for details.
+---
+<p align="center">
+  Made with ❤️ by <a href="https://github.com/D3vEduardo">@D3vEduardo</a>
+</p>

package/dist/api-docs.html ADDED Viewed

@@ -0,0 +1,41 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Versum API - Sistine Chapel Theme</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="app">Carregando...</div>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+    <script>
+      fetch("&{api_spec_url}")
+        .then((res) => {
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          return res.json();
+        })
+        .then((spec) => {
+          console.log("Spec carregado:", spec);
+          Scalar.createApiReference("#app", {
+            spec: {
+              content: spec,
+            },
+            proxy: "&{proxy_url}",
+            theme: "default",
+          });
+        })
+        .catch((err) => {
+          console.error("Erro ao carregar spec:", err);
+          document.getElementById("app").innerHTML =
+            `<pre style="color: red; padding: 20px;">
+Erro ao carregar API spec: ${err.message}
+Verifique se a API está rodando em &{proxy_url}
+            </pre>`;
+        });
+    </script>
+  </body>
+</html>

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,116 @@
+import { RequestServer, ResponseServer, NextFunction } from 'azurajs/types';
+interface ScalarConfigType {
+    apiSpecUrl: string;
+    proxyUrl: string;
+    customHtmlPath?: string;
+}
+interface ScalarStoreType {
+    proxy_url?: string;
+    api_spec_url?: string;
+    custom_html_path?: string;
+}
+type ProxyMiddlewareType = (req: RequestServer, res: ResponseServer, next?: NextFunction) => Promise<void>;
+interface ProxyOptions {
+    apiSpecUrl: string;
+}
+/**
+ * @fileoverview Scalar client for API documentation proxy
+ * This module provides a client for setting up API documentation with proxy capabilities
+ */
+/**
+ * Scalar client class for managing API documentation proxy
+ */
+declare class Scalar {
+    /**
+     * Middleware function that handles proxying requests to the API specification
+     */
+    proxyMiddleware: ProxyMiddlewareType;
+    /**
+     * Creates a new Scalar client instance
+     * @param config Configuration object for the Scalar client
+     */
+    constructor(config: ScalarConfigType);
+    /**
+     * Validates the provided configuration
+     * @param config Configuration object to validate
+     * @throws ScalarError if configuration is invalid
+     */
+    private validateConfig;
+}
+/**
+ * @fileoverview Controller for serving Scalar API documentation
+ * This module handles serving the API documentation HTML with proper URL replacements
+ */
+/**
+ * Serves the Scalar API documentation HTML page
+ * Replaces placeholders in the HTML template with actual URLs from the store
+ * @param res Response object to send the HTML to
+ * @returns Promise that resolves when the response is sent
+ */
+declare function getScalarDocs(res: ResponseServer): Promise<ResponseServer>;
+/**
+ * @fileoverview Proxy middleware for API requests
+ * This module provides a proxy middleware that forwards requests to the API specification
+ */
+/**
+ * Creates a proxy middleware function that forwards requests to the API specification
+ * @param options Configuration options for the proxy
+ * @returns Middleware function that handles proxying requests
+ */
+declare function proxyMiddleware({ apiSpecUrl, }: ProxyOptions): (req: RequestServer, res: ResponseServer, next?: NextFunction) => Promise<void>;
+/**
+ * @fileoverview Store utility for managing application state
+ * This module provides a typed store for managing scalar configuration values
+ */
+/**
+ * Typed store class for managing scalar configuration values
+ */
+declare class ScalarStore {
+    private store;
+    /**
+     * Sets a value in the store
+     * @param key The key to set
+     * @param value The value to set (if undefined, the key will be removed)
+     */
+    set<K extends keyof ScalarStoreType>(key: K, value: ScalarStoreType[K]): void;
+    /**
+     * Gets a value from the store
+     * @param key The key to get
+     * @returns The value associated with the key
+     */
+    get<K extends keyof ScalarStoreType>(key: K): ScalarStoreType[K];
+    /**
+     * Checks if a key exists in the store
+     * @param key The key to check
+     * @returns True if the key exists, false otherwise
+     */
+    has(key: keyof ScalarStoreType): boolean;
+    /**
+     * Deletes a key from the store
+     * @param key The key to delete
+     * @returns True if the key existed and was deleted, false otherwise
+     */
+    delete(key: keyof ScalarStoreType): boolean;
+    /**
+     * Clears all values from the store
+     */
+    clear(): void;
+    /**
+     * Gets all values from the store
+     * @returns An object containing all key-value pairs in the store
+     */
+    getAll(): ScalarStoreType;
+    [key: string]: any;
+}
+declare const store: ScalarStore;
+export { type ProxyMiddlewareType, Scalar, type ScalarConfigType, getScalarDocs, proxyMiddleware, store };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,245 @@
+// src/config/types.ts
+var ScalarError = class _ScalarError extends Error {
+  constructor(message, code, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    Object.setPrototypeOf(this, _ScalarError.prototype);
+  }
+};
+// src/middleware/proxy.ts
+import { logger } from "azurajs/logger";
+function proxyMiddleware({
+  apiSpecUrl
+}) {
+  return async (req, res, _next) => {
+    try {
+      if (!req.url || !req.method) {
+        res.status(400).json({
+          error: "Request URL and method are required",
+          code: "INVALID_REQUEST"
+        });
+        return;
+      }
+      logger("info", `[PROXY] ${req.method} ${req.url}`);
+      const url = new URL(req.url, "http://localhost");
+      const targetUrl = apiSpecUrl + url.pathname + url.search;
+      logger("info", `[PROXY] Forwarding to: ${targetUrl}`);
+      const headers = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value) {
+          headers[key] = Array.isArray(value) ? value.join(", ") : value;
+        }
+      }
+      headers.host = new URL(apiSpecUrl).host;
+      let body = null;
+      if (!["GET", "HEAD"].includes(req.method)) {
+        if (req.body) {
+          if (typeof req.body === "string") {
+            body = req.body;
+          } else if (typeof req.body === "object") {
+            body = JSON.stringify(req.body);
+          }
+        }
+      }
+      const proxyRes = await fetch(targetUrl, {
+        method: req.method,
+        headers,
+        body
+      });
+      logger("info", `[PROXY] Response: ${proxyRes.status}`);
+      const responseHeaders = {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET,POST,PUT,PATCH,DELETE,OPTIONS",
+        "Access-Control-Allow-Headers": "*"
+      };
+      for (const [key, value] of proxyRes.headers.entries()) {
+        if (!key.toLowerCase().startsWith("access-control-")) {
+          responseHeaders[key] = value;
+        }
+      }
+      res.writeHead(proxyRes.status, responseHeaders);
+      if (req.method === "OPTIONS") {
+        res.end();
+        return;
+      }
+      const buffer = Buffer.from(await proxyRes.arrayBuffer());
+      res.end(buffer);
+    } catch (err) {
+      logger("error", `[PROXY] Error: ${err}`);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        error: "Proxy error",
+        details: err instanceof Error ? err.message : String(err),
+        code: "PROXY_ERROR"
+      }));
+    }
+  };
+}
+// src/utils/store.ts
+var ScalarStore = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Sets a value in the store
+   * @param key The key to set
+   * @param value The value to set (if undefined, the key will be removed)
+   */
+  set(key, value) {
+    this.store.set(key, value);
+  }
+  /**
+   * Gets a value from the store
+   * @param key The key to get
+   * @returns The value associated with the key
+   */
+  get(key) {
+    return this.store.get(key);
+  }
+  /**
+   * Checks if a key exists in the store
+   * @param key The key to check
+   * @returns True if the key exists, false otherwise
+   */
+  has(key) {
+    return this.store.has(key);
+  }
+  /**
+   * Deletes a key from the store
+   * @param key The key to delete
+   * @returns True if the key existed and was deleted, false otherwise
+   */
+  delete(key) {
+    return this.store.delete(key);
+  }
+  /**
+   * Clears all values from the store
+   */
+  clear() {
+    this.store.clear();
+  }
+  /**
+   * Gets all values from the store
+   * @returns An object containing all key-value pairs in the store
+   */
+  getAll() {
+    const result = {};
+    for (const [key, value] of this.store.entries()) {
+      result[key] = value;
+    }
+    return result;
+  }
+};
+var store = new ScalarStore();
+// src/client.ts
+var Scalar = class {
+  /**
+   * Creates a new Scalar client instance
+   * @param config Configuration object for the Scalar client
+   */
+  constructor(config) {
+    this.validateConfig(config);
+    store.set("proxy_url", config.proxyUrl);
+    store.set("api_spec_url", config.apiSpecUrl);
+    store.set("custom_html_path", config.customHtmlPath);
+    this.proxyMiddleware = proxyMiddleware({ apiSpecUrl: config.apiSpecUrl });
+  }
+  /**
+   * Validates the provided configuration
+   * @param config Configuration object to validate
+   * @throws ScalarError if configuration is invalid
+   */
+  validateConfig(config) {
+    if (!config.apiSpecUrl) {
+      throw new ScalarError(
+        "apiSpecUrl is required",
+        "MISSING_API_SPEC_URL",
+        400
+      );
+    }
+    if (!config.proxyUrl) {
+      throw new ScalarError(
+        "proxyUrl is required",
+        "MISSING_PROXY_URL",
+        400
+      );
+    }
+    try {
+      new URL(config.apiSpecUrl);
+    } catch (error) {
+      throw new ScalarError(
+        "apiSpecUrl must be a valid URL",
+        "INVALID_API_SPEC_URL",
+        400
+      );
+    }
+    try {
+      new URL(config.proxyUrl);
+    } catch (error) {
+      throw new ScalarError(
+        "proxyUrl must be a valid URL",
+        "INVALID_PROXY_URL",
+        400
+      );
+    }
+  }
+};
+// src/controller.ts
+import { fileURLToPath } from "url";
+import path from "path";
+import fs from "fs";
+import { logger as logger2 } from "azurajs/logger";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+async function getScalarDocs(res) {
+  try {
+    const customHtmlPath = store.get("custom_html_path");
+    const proxyUrl = store.get("proxy_url");
+    const apiSpecUrl = store.get("api_spec_url");
+    if (!proxyUrl || !apiSpecUrl) {
+      throw new ScalarError(
+        "Proxy URL or API Spec URL not defined in store",
+        "STORE_VALUES_MISSING",
+        500
+      );
+    }
+    const htmlPath = customHtmlPath || path.join(__dirname, "./api-docs.html");
+    if (!fs.existsSync(htmlPath)) {
+      throw new ScalarError(
+        `HTML template file not found at path: ${htmlPath}`,
+        "HTML_TEMPLATE_NOT_FOUND",
+        404
+      );
+    }
+    const html = fs.readFileSync(htmlPath, "utf-8");
+    const processedHtml = html.replace(/&{proxy_url}/g, proxyUrl).replace(/&{api_spec_url}/g, apiSpecUrl);
+    return res.send(processedHtml);
+  } catch (error) {
+    if (error instanceof ScalarError) {
+      logger2("error", `[ScalarError] ${error.message}`);
+      return res.status(error.statusCode).json({
+        message: error.message,
+        code: error.code
+      });
+    } else {
+      logger2("error", String(error));
+      return res.status(500).json({
+        message: "Internal server error occurred while serving documentation",
+        code: "INTERNAL_SERVER_ERROR"
+      });
+    }
+  }
+}
+export {
+  Scalar,
+  ScalarError,
+  getScalarDocs,
+  proxyMiddleware,
+  store
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"sources":["../src/config/types.ts","../src/middleware/proxy.ts","../src/utils/store.ts","../src/client.ts","../src/controller.ts"],"sourcesContent":["import { NextFunction, RequestServer, ResponseServer } from \"azurajs/types\";\n\nexport interface ScalarConfigType {\n apiSpecUrl: string;\n proxyUrl: string;\n customHtmlPath?: string; // Optional since it might not always be provided\n}\n\nexport interface ScalarStoreType {\n proxy_url?: string;\n api_spec_url?: string;\n custom_html_path?: string;\n}\n\nexport type ProxyMiddlewareType = (\n req: RequestServer,\n res: ResponseServer,\n next?: NextFunction,\n) => Promise<void>;\n\n// Define specific error types\nexport class ScalarError extends Error {\n public readonly code: string;\n public readonly statusCode: number;\n\n constructor(message: string, code: string, statusCode: number) {\n super(message);\n this.code = code;\n this.statusCode = statusCode;\n Object.setPrototypeOf(this, ScalarError.prototype);\n }\n}\n\nexport interface ProxyOptions {\n apiSpecUrl: string;\n}\n","/**\n * @fileoverview Proxy middleware for API requests\n * This module provides a proxy middleware that forwards requests to the API specification\n */\n\nimport { ProxyOptions } from \"../config/types\";\nimport { NextFunction, RequestServer, ResponseServer } from \"azurajs/types\";\nimport { logger } from \"azurajs/logger\";\n\n/**\n * Creates a proxy middleware function that forwards requests to the API specification\n * @param options Configuration options for the proxy\n * @returns Middleware function that handles proxying requests\n */\nexport function proxyMiddleware({\n apiSpecUrl,\n}: ProxyOptions): (\n req: RequestServer,\n res: ResponseServer,\n next?: NextFunction,\n) => Promise<void> {\n return async (\n req: RequestServer,\n res: ResponseServer,\n _next?: NextFunction,\n ): Promise<void> => {\n try {\n if (!req.url || !req.method) {\n res.status(400).json({\n error: \"Request URL and method are required\",\n code: \"INVALID_REQUEST\"\n });\n return;\n }\n\n logger(\"info\", `[PROXY] ${req.method} ${req.url}`);\n\n const url = new URL(req.url, \"http://localhost\");\n const targetUrl = apiSpecUrl + url.pathname + url.search;\n\n logger(\"info\", `[PROXY] Forwarding to: ${targetUrl}`);\n\n // Convert Node.js headers to a format compatible with fetch\n const headers: Record<string, string> = {};\n for (const [key, value] of Object.entries(req.headers)) {\n if (value) {\n headers[key] = Array.isArray(value) ? value.join(\", \") : value;\n }\n }\n headers.host = new URL(apiSpecUrl).host;\n\n // Prepare request body\n let body: BodyInit | null = null;\n if (![\"GET\", \"HEAD\"].includes(req.method)) {\n // For non-GET/HEAD requests, we need to properly serialize the body\n // Since req might contain various data types, we need to handle appropriately\n if (req.body) {\n if (typeof req.body === 'string') {\n body = req.body;\n } else if (typeof req.body === 'object') {\n body = JSON.stringify(req.body);\n }\n }\n }\n\n const proxyRes = await fetch(targetUrl, {\n method: req.method,\n headers,\n body,\n });\n\n logger(\"info\", `[PROXY] Response: ${proxyRes.status}`);\n\n // CORS - IMPORTANT: define before copying response headers\n const responseHeaders: Record<string, string> = {\n \"Access-Control-Allow-Origin\": \"*\",\n \"Access-Control-Allow-Methods\": \"GET,POST,PUT,PATCH,DELETE,OPTIONS\",\n \"Access-Control-Allow-Headers\": \"*\",\n };\n\n // Copy response headers, avoiding CORS header conflicts\n for (const [key, value] of proxyRes.headers.entries()) {\n // Don't overwrite CORS headers\n if (!key.toLowerCase().startsWith(\"access-control-\")) {\n responseHeaders[key] = value;\n }\n }\n\n res.writeHead(proxyRes.status, responseHeaders);\n\n if (req.method === \"OPTIONS\") {\n res.end();\n return;\n }\n\n const buffer = Buffer.from(await proxyRes.arrayBuffer());\n res.end(buffer);\n } catch (err) {\n logger(\"error\", `[PROXY] Error: ${err}`);\n res.writeHead(500, { \"Content-Type\": \"application/json\" });\n res.end(JSON.stringify({\n error: \"Proxy error\",\n details: err instanceof Error ? err.message : String(err),\n code: \"PROXY_ERROR\"\n }));\n }\n };\n}\n","/**\n * @fileoverview Store utility for managing application state\n * This module provides a typed store for managing scalar configuration values\n */\n\nimport { ScalarStoreType } from \"../config/types\";\n\n/**\n * Typed store class for managing scalar configuration values\n */\nclass ScalarStore {\n private store: Map<keyof ScalarStoreType, string | undefined> = new Map();\n\n /**\n * Sets a value in the store\n * @param key The key to set\n * @param value The value to set (if undefined, the key will be removed)\n */\n set<K extends keyof ScalarStoreType>(key: K, value: ScalarStoreType[K]): void {\n this.store.set(key, value as string | undefined);\n }\n\n /**\n * Gets a value from the store\n * @param key The key to get\n * @returns The value associated with the key\n */\n get<K extends keyof ScalarStoreType>(key: K): ScalarStoreType[K] {\n return this.store.get(key) as ScalarStoreType[K];\n }\n\n /**\n * Checks if a key exists in the store\n * @param key The key to check\n * @returns True if the key exists, false otherwise\n */\n has(key: keyof ScalarStoreType): boolean {\n return this.store.has(key);\n }\n\n /**\n * Deletes a key from the store\n * @param key The key to delete\n * @returns True if the key existed and was deleted, false otherwise\n */\n delete(key: keyof ScalarStoreType): boolean {\n return this.store.delete(key);\n }\n\n /**\n * Clears all values from the store\n */\n clear(): void {\n this.store.clear();\n }\n\n /**\n * Gets all values from the store\n * @returns An object containing all key-value pairs in the store\n */\n getAll(): ScalarStoreType {\n const result: Partial<ScalarStoreType> = {};\n for (const [key, value] of this.store.entries()) {\n result[key] = value as ScalarStoreType[keyof ScalarStoreType];\n }\n return result as ScalarStoreType;\n }\n\n // Index signature to allow direct property access\n [key: string]: any;\n}\n\nexport const store = new ScalarStore();\n","/**\n * @fileoverview Scalar client for API documentation proxy\n * This module provides a client for setting up API documentation with proxy capabilities\n */\n\nimport { ProxyMiddlewareType, ScalarConfigType, ScalarError } from \"./config/types\";\nimport { proxyMiddleware } from \"./middleware/proxy\";\nimport { store } from \"./utils/store\";\n\n/**\n * Scalar client class for managing API documentation proxy\n */\nexport class Scalar {\n /**\n * Middleware function that handles proxying requests to the API specification\n */\n public proxyMiddleware: ProxyMiddlewareType;\n\n /**\n * Creates a new Scalar client instance\n * @param config Configuration object for the Scalar client\n */\n constructor(config: ScalarConfigType) {\n this.validateConfig(config);\n\n store.set(\"proxy_url\", config.proxyUrl);\n store.set(\"api_spec_url\", config.apiSpecUrl);\n store.set(\"custom_html_path\", config.customHtmlPath);\n\n this.proxyMiddleware = proxyMiddleware({ apiSpecUrl: config.apiSpecUrl });\n }\n\n /**\n * Validates the provided configuration\n * @param config Configuration object to validate\n * @throws ScalarError if configuration is invalid\n */\n private validateConfig(config: ScalarConfigType): void {\n if (!config.apiSpecUrl) {\n throw new ScalarError(\n \"apiSpecUrl is required\",\n \"MISSING_API_SPEC_URL\",\n 400\n );\n }\n\n if (!config.proxyUrl) {\n throw new ScalarError(\n \"proxyUrl is required\",\n \"MISSING_PROXY_URL\",\n 400\n );\n }\n\n try {\n new URL(config.apiSpecUrl);\n } catch (error) {\n throw new ScalarError(\n \"apiSpecUrl must be a valid URL\",\n \"INVALID_API_SPEC_URL\",\n 400\n );\n }\n\n try {\n new URL(config.proxyUrl);\n } catch (error) {\n throw new ScalarError(\n \"proxyUrl must be a valid URL\",\n \"INVALID_PROXY_URL\",\n 400\n );\n }\n }\n}\n","/**\n * @fileoverview Controller for serving Scalar API documentation\n * This module handles serving the API documentation HTML with proper URL replacements\n */\n\nimport { fileURLToPath } from \"node:url\";\nimport path from \"node:path\";\nimport fs from \"fs\";\nimport { logger } from \"azurajs/logger\";\nimport { ResponseServer } from \"azurajs/types\";\nimport { store } from \"./utils/store\";\nimport { ScalarError } from \"./config/types\";\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n/**\n * Serves the Scalar API documentation HTML page\n * Replaces placeholders in the HTML template with actual URLs from the store\n * @param res Response object to send the HTML to\n * @returns Promise that resolves when the response is sent\n */\nexport async function getScalarDocs(res: ResponseServer) {\n try {\n const customHtmlPath = store.get(\"custom_html_path\");\n const proxyUrl = store.get(\"proxy_url\");\n const apiSpecUrl = store.get(\"api_spec_url\");\n\n if (!proxyUrl || !apiSpecUrl) {\n throw new ScalarError(\n \"Proxy URL or API Spec URL not defined in store\",\n \"STORE_VALUES_MISSING\",\n 500\n );\n }\n\n const htmlPath = customHtmlPath || path.join(__dirname, \"./api-docs.html\");\n\n if (!fs.existsSync(htmlPath)) {\n throw new ScalarError(\n `HTML template file not found at path: ${htmlPath}`,\n \"HTML_TEMPLATE_NOT_FOUND\",\n 404\n );\n }\n\n const html = fs.readFileSync(htmlPath, \"utf-8\");\n const processedHtml = html\n .replace(/&{proxy_url}/g, proxyUrl)\n .replace(/&{api_spec_url}/g, apiSpecUrl);\n\n return res.send(processedHtml);\n } catch (error) {\n if (error instanceof ScalarError) {\n logger(\"error\", `[ScalarError] ${error.message}`);\n return res.status(error.statusCode).json({\n message: error.message,\n code: error.code,\n });\n } else {\n logger(\"error\", String(error));\n return res.status(500).json({\n message: \"Internal server error occurred while serving documentation\",\n code: \"INTERNAL_SERVER_ERROR\",\n });\n }\n }\n}\n"],"mappings":";AAqBO,IAAM,cAAN,MAAM,qBAAoB,MAAM;AAAA,EAIrC,YAAY,SAAiB,MAAc,YAAoB;AAC7D,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,aAAa;AAClB,WAAO,eAAe,MAAM,aAAY,SAAS;AAAA,EACnD;AACF;;;ACxBA,SAAS,cAAc;AAOhB,SAAS,gBAAgB;AAAA,EAC9B;AACF,GAImB;AACjB,SAAO,OACL,KACA,KACA,UACkB;AAClB,QAAI;AACF,UAAI,CAAC,IAAI,OAAO,CAAC,IAAI,QAAQ;AAC3B,YAAI,OAAO,GAAG,EAAE,KAAK;AAAA,UACnB,OAAO;AAAA,UACP,MAAM;AAAA,QACR,CAAC;AACD;AAAA,MACF;AAEA,aAAO,QAAQ,WAAW,IAAI,MAAM,IAAI,IAAI,GAAG,EAAE;AAEjD,YAAM,MAAM,IAAI,IAAI,IAAI,KAAK,kBAAkB;AAC/C,YAAM,YAAY,aAAa,IAAI,WAAW,IAAI;AAElD,aAAO,QAAQ,0BAA0B,SAAS,EAAE;AAGpD,YAAM,UAAkC,CAAC;AACzC,iBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,OAAO,GAAG;AACtD,YAAI,OAAO;AACT,kBAAQ,GAAG,IAAI,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,IAAI,IAAI;AAAA,QAC3D;AAAA,MACF;AACA,cAAQ,OAAO,IAAI,IAAI,UAAU,EAAE;AAGnC,UAAI,OAAwB;AAC5B,UAAI,CAAC,CAAC,OAAO,MAAM,EAAE,SAAS,IAAI,MAAM,GAAG;AAGzC,YAAI,IAAI,MAAM;AACZ,cAAI,OAAO,IAAI,SAAS,UAAU;AAChC,mBAAO,IAAI;AAAA,UACb,WAAW,OAAO,IAAI,SAAS,UAAU;AACvC,mBAAO,KAAK,UAAU,IAAI,IAAI;AAAA,UAChC;AAAA,QACF;AAAA,MACF;AAEA,YAAM,WAAW,MAAM,MAAM,WAAW;AAAA,QACtC,QAAQ,IAAI;AAAA,QACZ;AAAA,QACA;AAAA,MACF,CAAC;AAED,aAAO,QAAQ,qBAAqB,SAAS,MAAM,EAAE;AAGrD,YAAM,kBAA0C;AAAA,QAC9C,+BAA+B;AAAA,QAC/B,gCAAgC;AAAA,QAChC,gCAAgC;AAAA,MAClC;AAGA,iBAAW,CAAC,KAAK,KAAK,KAAK,SAAS,QAAQ,QAAQ,GAAG;AAErD,YAAI,CAAC,IAAI,YAAY,EAAE,WAAW,iBAAiB,GAAG;AACpD,0BAAgB,GAAG,IAAI;AAAA,QACzB;AAAA,MACF;AAEA,UAAI,UAAU,SAAS,QAAQ,eAAe;AAE9C,UAAI,IAAI,WAAW,WAAW;AAC5B,YAAI,IAAI;AACR;AAAA,MACF;AAEA,YAAM,SAAS,OAAO,KAAK,MAAM,SAAS,YAAY,CAAC;AACvD,UAAI,IAAI,MAAM;AAAA,IAChB,SAAS,KAAK;AACZ,aAAO,SAAS,kBAAkB,GAAG,EAAE;AACvC,UAAI,UAAU,KAAK,EAAE,gBAAgB,mBAAmB,CAAC;AACzD,UAAI,IAAI,KAAK,UAAU;AAAA,QACrB,OAAO;AAAA,QACP,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,QACxD,MAAM;AAAA,MACR,CAAC,CAAC;AAAA,IACJ;AAAA,EACF;AACF;;;ACjGA,IAAM,cAAN,MAAkB;AAAA,EAAlB;AACE,SAAQ,QAAwD,oBAAI,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOxE,IAAqC,KAAQ,OAAiC;AAC5E,SAAK,MAAM,IAAI,KAAK,KAA2B;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAqC,KAA4B;AAC/D,WAAO,KAAK,MAAM,IAAI,GAAG;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,KAAqC;AACvC,WAAO,KAAK,MAAM,IAAI,GAAG;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAO,KAAqC;AAC1C,WAAO,KAAK,MAAM,OAAO,GAAG;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACZ,SAAK,MAAM,MAAM;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAA0B;AACxB,UAAM,SAAmC,CAAC;AAC1C,eAAW,CAAC,KAAK,KAAK,KAAK,KAAK,MAAM,QAAQ,GAAG;AAC/C,aAAO,GAAG,IAAI;AAAA,IAChB;AACA,WAAO;AAAA,EACT;AAIF;AAEO,IAAM,QAAQ,IAAI,YAAY;;;AC5D9B,IAAM,SAAN,MAAa;AAAA;AAAA;AAAA;AAAA;AAAA,EAUlB,YAAY,QAA0B;AACpC,SAAK,eAAe,MAAM;AAE1B,UAAM,IAAI,aAAa,OAAO,QAAQ;AACtC,UAAM,IAAI,gBAAgB,OAAO,UAAU;AAC3C,UAAM,IAAI,oBAAoB,OAAO,cAAc;AAEnD,SAAK,kBAAkB,gBAAgB,EAAE,YAAY,OAAO,WAAW,CAAC;AAAA,EAC1E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOQ,eAAe,QAAgC;AACrD,QAAI,CAAC,OAAO,YAAY;AACtB,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,QAAI,CAAC,OAAO,UAAU;AACpB,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,QAAI;AACF,UAAI,IAAI,OAAO,UAAU;AAAA,IAC3B,SAAS,OAAO;AACd,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,QAAI;AACF,UAAI,IAAI,OAAO,QAAQ;AAAA,IACzB,SAAS,OAAO;AACd,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;;;ACrEA,SAAS,qBAAqB;AAC9B,OAAO,UAAU;AACjB,OAAO,QAAQ;AACf,SAAS,UAAAA,eAAc;AAKvB,IAAM,aAAa,cAAc,YAAY,GAAG;AAChD,IAAM,YAAY,KAAK,QAAQ,UAAU;AAQzC,eAAsB,cAAc,KAAqB;AACvD,MAAI;AACF,UAAM,iBAAiB,MAAM,IAAI,kBAAkB;AACnD,UAAM,WAAW,MAAM,IAAI,WAAW;AACtC,UAAM,aAAa,MAAM,IAAI,cAAc;AAE3C,QAAI,CAAC,YAAY,CAAC,YAAY;AAC5B,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,UAAM,WAAW,kBAAkB,KAAK,KAAK,WAAW,iBAAiB;AAEzE,QAAI,CAAC,GAAG,WAAW,QAAQ,GAAG;AAC5B,YAAM,IAAI;AAAA,QACR,yCAAyC,QAAQ;AAAA,QACjD;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,UAAM,OAAO,GAAG,aAAa,UAAU,OAAO;AAC9C,UAAM,gBAAgB,KACnB,QAAQ,iBAAiB,QAAQ,EACjC,QAAQ,oBAAoB,UAAU;AAEzC,WAAO,IAAI,KAAK,aAAa;AAAA,EAC/B,SAAS,OAAO;AACd,QAAI,iBAAiB,aAAa;AAChC,MAAAC,QAAO,SAAS,iBAAiB,MAAM,OAAO,EAAE;AAChD,aAAO,IAAI,OAAO,MAAM,UAAU,EAAE,KAAK;AAAA,QACvC,SAAS,MAAM;AAAA,QACf,MAAM,MAAM;AAAA,MACd,CAAC;AAAA,IACH,OAAO;AACL,MAAAA,QAAO,SAAS,OAAO,KAAK,CAAC;AAC7B,aAAO,IAAI,OAAO,GAAG,EAAE,KAAK;AAAA,QAC1B,SAAS;AAAA,QACT,MAAM;AAAA,MACR,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":["logger","logger"]}

package/package.json ADDED Viewed

@@ -0,0 +1,26 @@
+{
+  "name": "azurajs-scalar",
+  "version": "1.0.0",
+  "description": "Proxy middleware and controller to scalar documentation.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.25.0",
+  "dependencies": {
+    "azurajs": "2.6.1-1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}