@ir-kit/spec-docs 0.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ahmed Rowaihi
+
+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.

package/README.md

@@ -0,0 +1,43 @@
+# `@ir-kit/spec-docs`
+
+Render any supported API spec as a standalone HTML documentation page via [Scalar API Reference](https://github.com/scalar/scalar). Converts the input to OpenAPI 3 first (using `@ir-kit/spec-convert`), then delegates HTML emission to `@scalar/core`'s `getHtmlDocument` — the same renderer the official Express / Hono / Fastify integrations use.
+
+Part of [ir-kit](https://github.com/ir-kit/ir-kit).
+
+## Install
+
+```sh
+npm install @ir-kit/spec-docs
+```
+
+## Usage
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { renderDocs } from "@ir-kit/spec-docs";
+
+const { html } = await renderDocs({
+  input: "./api.yaml", // postman / proto / typespec / openapi3 / asyncapi3
+  theme: "moon", // optional Scalar theme
+});
+
+await writeFile("docs.html", html);
+```
+
+The output is a self-contained HTML page that loads Scalar from CDN — no bundler required, ready to drop on any static host.
+
+## API
+
+| Export                                               | Description                                                           |
+| ---------------------------------------------------- | --------------------------------------------------------------------- |
+| `renderDocs(opts)`                                   | Convert spec to OpenAPI 3 if needed, return `{ html, openapi, from }` |
+| `RenderDocsOptions`, `RenderDocsResult`, `DocsTheme` | Public types                                                          |
+
+Any input format supported by [`@ir-kit/spec-convert`](../spec-convert) works (currently: openapi3, postman, proto, typespec, asyncapi3, json-schema).
+
+## CLI
+
+```sh
+ir docs ./api.yaml --out docs.html
+ir docs ./collection.postman_collection.json --theme moon --out docs.html
+```

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import type { ConvertSpecInput, SpecDocument, SpecFormat } from "@ir-kit/spec-convert";
+export type DocsTheme = "default" | "alternate" | "moon" | "purple" | "solarized" | "bluePlanet" | "saturn" | "kepler" | "mars" | "deepSpace" | "none";
+export interface RenderDocsOptions {
+    input: ConvertSpecInput;
+    from?: SpecFormat;
+    cwd?: string;
+    theme?: DocsTheme;
+    /** Extra Scalar configuration merged into the HTML render. */
+    scalar?: Record<string, unknown>;
+}
+export interface RenderDocsResult {
+    html: string;
+    openapi: SpecDocument;
+    from: SpecFormat;
+}
+/**
+ * Render any supported spec format as a standalone HTML page via
+ * Scalar API Reference. Converts to OpenAPI 3 first (if needed), then
+ * delegates HTML emission to `@scalar/core` — same renderer used by
+ * the official Express/Hono/Fastify integrations.
+ */
+export declare function renderDocs(opts: RenderDocsOptions): Promise<RenderDocsResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACX,MAAM,sBAAsB,CAAC;AAK9B,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,WAAW,GACX,MAAM,GACN,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,WAAW,GACX,MAAM,CAAC;AAEX,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAmB3B"}

package/dist/index.js

@@ -0,0 +1,27 @@
+import { convertSpec } from "@ir-kit/spec-convert";
+import { getHtmlDocument } from "@scalar/core/libs/html-rendering";
+/**
+ * Render any supported spec format as a standalone HTML page via
+ * Scalar API Reference. Converts to OpenAPI 3 first (if needed), then
+ * delegates HTML emission to `@scalar/core` — same renderer used by
+ * the official Express/Hono/Fastify integrations.
+ */
+export async function renderDocs(opts) {
+    const result = await convertSpec({
+        input: opts.input,
+        from: opts.from,
+        to: "openapi3",
+        cwd: opts.cwd,
+    });
+    if (result.output.kind !== "document") {
+        throw new Error(`Unexpected converter output kind '${result.output.kind}' for openapi3 target`);
+    }
+    const openapi = result.output.document;
+    const html = getHtmlDocument({
+        content: openapi,
+        ...(opts.theme ? { theme: opts.theme } : {}),
+        ...opts.scalar,
+    });
+    return { html, openapi, from: result.from };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AA8BnE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC;QAC/B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,EAAE,EAAE,UAAU;QACd,GAAG,EAAE,IAAI,CAAC,GAAG;KACd,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,qCAAqC,MAAM,CAAC,MAAM,CAAC,IAAI,uBAAuB,CAC/E,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;IACvC,MAAM,IAAI,GAAG,eAAe,CAAC;QAC3B,OAAO,EAAE,OAAO;QAChB,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,GAAG,IAAI,CAAC,MAAM;KACf,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@ir-kit/spec-docs",
+  "version": "0.2.0",
+  "description": "Render any API spec as standalone HTML documentation via Scalar API Reference. Programmatic + CLI.",
+  "keywords": [
+    "openapi",
+    "asyncapi",
+    "typespec",
+    "protobuf",
+    "postman",
+    "docs",
+    "scalar",
+    "ir-kit"
+  ],
+  "homepage": "https://github.com/ir-kit/ir-kit/tree/main/packages/shared/spec-docs",
+  "bugs": {
+    "url": "https://github.com/ir-kit/ir-kit/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Ahmed Rowaihi",
+    "email": "ahmedrowaihi@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ir-kit/ir-kit.git",
+    "directory": "packages/shared/spec-docs"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@scalar/core": "^0.5.9",
+    "@ir-kit/spec-convert": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "vitest": "^4.0.0",
+    "@ir-kit/tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}