@itsbjoern/roost 0.1.4 → 0.1.7

package/README.md

@@ -1,19 +1,31 @@
 ## @itsbjoern/roost
 
-This is the npm wrapper for the Roost CLI.
-
-It downloads a prebuilt `roost` binary from the GitHub Releases of `itsbjoern/roost`
-for your platform and exposes it as the `roost` command.
+This is the npm wrapper for the Roost CLI. It downloads a prebuilt `roost` binary from GitHub Releases and exposes the `roost` command. You can also use the **JavaScript API** from Node without shelling out.
 
 ### Install
 
 ```bash
 npm install -g @itsbjoern/roost
+# or as a dependency:
+npm install @itsbjoern/roost
 ```
 
-Then:
+Then (CLI):
 
 ```bash
 roost init
 ```
 
+### JavaScript API
+
+Use the package as a library to get cert/key **contents** (or paths) for HTTPS config. Use `getDomainCerts` for build tools—returns literal PEM strings, no file reads:
+
+```js
+const { getDomainCerts } = require('@itsbjoern/roost');
+
+const { cert, key } = await getDomainCerts('api.local', { generate: true });
+// Pass cert and key directly to https.createServer or Vite server.https
+```
+
+See the [main README](https://github.com/itsbjoern/roost#javascript-api) for full API docs and examples.
+

package/index.d.ts

@@ -0,0 +1,58 @@
+import { type ExecFileOptions } from "child_process";
+/**
+ * Options for execFile when running the roost binary.
+ */
+export interface RunRoostOptions extends ExecFileOptions {
+}
+/**
+ * Options for domain path helpers. Can be combined with exec options.
+ * - generate: if true, run `domain add` when the domain doesn't exist
+ * - exact: when generating, create cert for exact domain only (no wildcard)
+ * - allow: when generating, allow any TLD (bypass allowlist)
+ */
+export interface DomainPathOptions extends RunRoostOptions {
+    generate?: boolean;
+    exact?: boolean;
+    allow?: boolean;
+}
+/**
+ * Resolved filesystem paths for a domain's certificate and private key.
+ * Returned by {@link getDomainPaths}.
+ */
+export interface DomainPaths {
+    cert: string;
+    key: string;
+}
+/**
+ * Literal certificate and private key contents (PEM strings).
+ * Returned by {@link getDomainCerts} for direct use with HTTPS config—no file reads needed.
+ */
+export interface DomainCerts {
+    cert: string;
+    key: string;
+}
+export declare function runRoost(args: string[], options?: RunRoostOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function getDomainPath(kind: "cert" | "key", domain: string, options?: DomainPathOptions): Promise<string>;
+export declare function getDomainCertPath(domain: string, options?: DomainPathOptions): Promise<string>;
+export declare function getDomainKeyPath(domain: string, options?: DomainPathOptions): Promise<string>;
+/**
+ * Resolve both cert and key **paths** for a domain in one call.
+ *
+ * @param domain - Domain name (e.g. "api.local")
+ * @param options - Optional { generate, exact, allow } and/or exec options
+ * @returns Promise resolving to `{ cert: string, key: string }` (filesystem paths)
+ */
+export declare function getDomainPaths(domain: string, options?: DomainPathOptions): Promise<DomainPaths>;
+/**
+ * Resolve both cert and key **contents** (literal PEM strings) for a domain in one call.
+ * Build-tool friendly: pass the result directly to HTTPS config—no file reads needed.
+ * Use `generate: true` to create the domain if it doesn't exist.
+ *
+ * @param domain - Domain name (e.g. "api.local")
+ * @param options - Optional { generate, exact, allow } and/or exec options
+ * @returns Promise resolving to `{ cert: string, key: string }` (PEM file contents)
+ */
+export declare function getDomainCerts(domain: string, options?: DomainPathOptions): Promise<DomainCerts>;

package/index.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRoost = runRoost;
+exports.getDomainPath = getDomainPath;
+exports.getDomainCertPath = getDomainCertPath;
+exports.getDomainKeyPath = getDomainKeyPath;
+exports.getDomainPaths = getDomainPaths;
+exports.getDomainCerts = getDomainCerts;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const PATH_OPTION_KEYS = ["generate", "exact", "allow"];
+function getBinaryPath() {
+    const exeName = process.platform === "win32" ? "roost.exe" : "roost";
+    const exePath = path_1.default.join(__dirname, "bin", exeName);
+    if (!fs_1.default.existsSync(exePath)) {
+        const error = new Error("roost: binary not found. Make sure @itsbjoern/roost is installed and the postinstall step completed successfully.");
+        error.code = "ENOENT";
+        throw error;
+    }
+    return exePath;
+}
+function runRoost(args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const exePath = getBinaryPath();
+        (0, child_process_1.execFile)(exePath, args, {
+            encoding: "utf8",
+            ...options,
+        }, (error, stdout, stderr) => {
+            const out = typeof stdout === "string" ? stdout : stdout?.toString() ?? "";
+            const err = typeof stderr === "string" ? stderr : stderr?.toString() ?? "";
+            if (error) {
+                error.stdout = out;
+                error.stderr = err;
+                reject(error);
+                return;
+            }
+            resolve({ stdout: out, stderr: err });
+        });
+    });
+}
+function domainPathArgs(kind, domain, pathOptions = {}) {
+    const args = ["domain", "path", kind, domain];
+    if (pathOptions.generate)
+        args.push("--generate");
+    if (pathOptions.exact)
+        args.push("--exact");
+    if (pathOptions.allow)
+        args.push("--allow");
+    return args;
+}
+async function getDomainPath(kind, domain, options = {}) {
+    if (kind !== "cert" && kind !== "key") {
+        throw new Error(`Invalid kind "${kind}". Expected "cert" or "key".`);
+    }
+    if (!domain) {
+        throw new Error("Domain is required.");
+    }
+    const pathOptions = {};
+    const execOptions = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (PATH_OPTION_KEYS.includes(key)) {
+            pathOptions[key] = value;
+        }
+        else {
+            execOptions[key] = value;
+        }
+    }
+    const args = domainPathArgs(kind, domain, pathOptions);
+    const { stdout } = await runRoost(args, execOptions);
+    return stdout.trim();
+}
+async function getDomainCertPath(domain, options = {}) {
+    return getDomainPath("cert", domain, options);
+}
+async function getDomainKeyPath(domain, options = {}) {
+    return getDomainPath("key", domain, options);
+}
+/**
+ * Resolve both cert and key **paths** for a domain in one call.
+ *
+ * @param domain - Domain name (e.g. "api.local")
+ * @param options - Optional { generate, exact, allow } and/or exec options
+ * @returns Promise resolving to `{ cert: string, key: string }` (filesystem paths)
+ */
+async function getDomainPaths(domain, options = {}) {
+    const [cert, key] = await Promise.all([
+        getDomainCertPath(domain, options),
+        getDomainKeyPath(domain, options),
+    ]);
+    return { cert, key };
+}
+/**
+ * Resolve both cert and key **contents** (literal PEM strings) for a domain in one call.
+ * Build-tool friendly: pass the result directly to HTTPS config—no file reads needed.
+ * Use `generate: true` to create the domain if it doesn't exist.
+ *
+ * @param domain - Domain name (e.g. "api.local")
+ * @param options - Optional { generate, exact, allow } and/or exec options
+ * @returns Promise resolving to `{ cert: string, key: string }` (PEM file contents)
+ */
+async function getDomainCerts(domain, options = {}) {
+    const paths = await getDomainPaths(domain, options);
+    const [cert, key] = await Promise.all([
+        fs_1.default.promises.readFile(paths.cert, "utf8"),
+        fs_1.default.promises.readFile(paths.key, "utf8"),
+    ]);
+    return { cert, key };
+}

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@itsbjoern/roost",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "Roost CLI - local HTTPS reverse proxy with automatic cert management",
+  "main": "index.js",
+  "types": "index.d.ts",
   "bin": {
     "roost": "bin/roost"
   },
   "scripts": {
-    "postinstall": "node install.js"
+    "build": "tsc",
+    "postinstall": "node install.js",
+    "prepublishOnly": "npm run build"
   },
   "files": [
+    "index.js",
+    "index.d.ts",
     "bin/",
     "install.js",
     "README.md"
@@ -33,11 +39,15 @@
   },
   "homepage": "https://github.com/itsbjoern/roost#readme",
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "dependencies": {
     "tar": "^7.4.3"
   },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
   "publishConfig": {
     "access": "public"
   }