@fonoster/common 0.27.0 → 0.30.0

package/dist/config/index.js

@@ -0,0 +1,46 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+__exportStar(require("./configHints"), exports);
+__exportStar(require("./integrationsSchema"), exports);
+__exportStar(require("./interpolateEnv"), exports);
+__exportStar(require("./loadServiceConfig"), exports);
+__exportStar(require("./logsSchema"), exports);
+__exportStar(require("./parseConfigFile"), exports);
+__exportStar(require("./resolveConfigFile"), exports);
+__exportStar(require("./resolveSecretRefs"), exports);
+__exportStar(require("./strictDeep"), exports);
+__exportStar(require("./telemetrySchema"), exports);
+__exportStar(require("./natsConnection"), exports);
+__exportStar(require("./toJsonSchema"), exports);

package/dist/config/integrationsSchema.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+declare const integrationsConfigSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    productRef: z.ZodString;
+    type: z.ZodEnum<["tts", "stt", "llm"]>;
+    credentials: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type?: "tts" | "stt" | "llm";
+    name?: string;
+    productRef?: string;
+    credentials?: Record<string, unknown>;
+}, {
+    type?: "tts" | "stt" | "llm";
+    name?: string;
+    productRef?: string;
+    credentials?: Record<string, unknown>;
+}>, "many">;
+/** Spelled out so callers get required fields regardless of tsconfig strictness. */
+type IntegrationsConfig = Array<{
+    name: string;
+    productRef: string;
+    type: "tts" | "stt" | "llm";
+    credentials: Record<string, unknown>;
+}>;
+/**
+ * Reads and validates the retired integrations file. Only `fonoster-migrate-legacy --integrations`
+ * reads it now, to move its keys into operator config by credentialRef (add-provider-registry 5.3).
+ * YAML (`.yaml`/`.yml`) or JSON with comments (`.json`/`.jsonc`). Throws with the
+ * file path when the file can't be read or doesn't validate.
+ */
+declare function getIntegrationsFromFile(pathToIntegrations: string): IntegrationsConfig;
+export { integrationsConfigSchema, IntegrationsConfig, getIntegrationsFromFile };

package/dist/config/integrationsSchema.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.integrationsConfigSchema = void 0;
+exports.getIntegrationsFromFile = getIntegrationsFromFile;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const fs_1 = __importDefault(require("fs"));
+const zod_1 = require("zod");
+const zod_validation_error_1 = require("zod-validation-error");
+const parseConfigFile_1 = require("./parseConfigFile");
+const integrationsConfigSchema = zod_1.z.array(zod_1.z.object({
+    name: zod_1.z.string(),
+    productRef: zod_1.z.string(),
+    type: zod_1.z.enum(["tts", "stt", "llm"]),
+    credentials: zod_1.z.record(zod_1.z.unknown())
+}));
+exports.integrationsConfigSchema = integrationsConfigSchema;
+/**
+ * Reads and validates the retired integrations file. Only `fonoster-migrate-legacy --integrations`
+ * reads it now, to move its keys into operator config by credentialRef (add-provider-registry 5.3).
+ * YAML (`.yaml`/`.yml`) or JSON with comments (`.json`/`.jsonc`). Throws with the
+ * file path when the file can't be read or doesn't validate.
+ */
+function getIntegrationsFromFile(pathToIntegrations) {
+    let raw;
+    try {
+        raw = (0, parseConfigFile_1.parseConfigFile)(pathToIntegrations, fs_1.default.readFileSync(pathToIntegrations, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`unable to read integrations at ${pathToIntegrations}: ${e.message}`);
+    }
+    const result = integrationsConfigSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`invalid integrations at ${pathToIntegrations}: ${(0, zod_validation_error_1.fromError)(result.error, { prefix: null }).toString()}`);
+    }
+    return result.data;
+}

package/dist/config/interpolateEnv.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+type Env = Record<string, string | undefined>;
+type InterpolateOptions = {
+    /**
+     * Key paths where `${VAR}` may appear, e.g. `database.url` or `influxdb.*`
+     * (`*` matches the key and everything below it; `*` alone matches every key). When given,
+     * `${...}` at any other path is an error. When omitted, every string is interpolated.
+     */
+    allowedPaths?: string[];
+};
+/**
+ * Recursively walks an already-parsed config value and interpolates `${VAR}`
+ * references in its strings. Returns a new value; the input is not mutated.
+ * Errors name the key path where they happened.
+ */
+declare function interpolateEnv<T>(input: T, env?: Env, options?: InterpolateOptions): T;
+export { interpolateEnv, InterpolateOptions };

package/dist/config/interpolateEnv.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interpolateEnv = interpolateEnv;
+/**
+ * Shell / docker-compose style variable interpolation for config files.
+ *
+ * Supported forms inside any string value:
+ *   - `${VAR}`          -> value of VAR; throws if VAR is unset or empty
+ *   - `${VAR:-default}` -> value of VAR, or `default` when VAR is unset or empty
+ *
+ * Anything that is not a `${...}` reference is left untouched, so plain literals
+ * (`http://asterisk:8088`, `$5.00`, ...) pass through unchanged. Services limit
+ * it to values shared with other containers (see `allowedPaths`), so each value
+ * is written once.
+ */
+const VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(:-([^}]*))?\}/g;
+function interpolateString(value, env) {
+    return value.replace(VAR_PATTERN, (_match, name, hasDefault, fallback) => {
+        const current = env[name];
+        if (current !== undefined && current !== "") {
+            return current;
+        }
+        if (hasDefault !== undefined) {
+            return fallback;
+        }
+        throw new Error(`references undefined environment variable \${${name}} and no default was given`);
+    });
+}
+const HAS_REFERENCE = /\$\{[^}]*\}/;
+function isAllowed(path, allowedPaths) {
+    return allowedPaths.some((pattern) => pattern === "*"
+        ? true
+        : pattern.endsWith(".*")
+            ? path === pattern.slice(0, -2) ||
+                path.startsWith(`${pattern.slice(0, -2)}.`)
+            : path === pattern);
+}
+function walk(input, env, options, path) {
+    if (typeof input === "string") {
+        if (!HAS_REFERENCE.test(input)) {
+            return input;
+        }
+        const where = path || "(root)";
+        if (options.allowedPaths && !isAllowed(path, options.allowedPaths)) {
+            throw new Error(`${where}: \${...} is only allowed for values shared with other containers (${options.allowedPaths.join(", ") || "none here"})`);
+        }
+        try {
+            return interpolateString(input, env);
+        }
+        catch (e) {
+            throw new Error(`${where}: ${e.message}`);
+        }
+    }
+    if (Array.isArray(input)) {
+        return input.map((item, index) => walk(item, env, options, `${path}[${index}]`));
+    }
+    if (input !== null && typeof input === "object") {
+        const entries = Object.entries(input).map(([key, value]) => [key, walk(value, env, options, path ? `${path}.${key}` : key)]);
+        return Object.fromEntries(entries);
+    }
+    return input;
+}
+/**
+ * Recursively walks an already-parsed config value and interpolates `${VAR}`
+ * references in its strings. Returns a new value; the input is not mutated.
+ * Errors name the key path where they happened.
+ */
+function interpolateEnv(input, env = process.env, options = {}) {
+    return walk(input, env, options, "");
+}

package/dist/config/loadServiceConfig.d.ts

@@ -0,0 +1,33 @@
+import { z, ZodTypeAny } from "zod";
+import { MovedKeys } from "./configHints";
+type Env = Record<string, string | undefined>;
+type LoadServiceConfigOptions<S extends ZodTypeAny> = {
+    /** Service name, used in messages. */
+    service: string;
+    /** File name without extension. Defaults to `service`. */
+    fileBase?: string;
+    /** Zod schema that validates (and applies defaults to) the config. */
+    schema: S;
+    /** Defaults to `process.argv`; `--config <path>` picks the file. */
+    argv?: string[];
+    /** Only used to resolve `${VAR}` placeholders. Defaults to `process.env`. */
+    env?: Env;
+    /** Directories searched when `--config` is absent. */
+    searchDirs?: string[];
+    /**
+     * Key paths that may reference `${VAR}` (values Compose passes from `.env`). `["*"]` allows
+     * every key (the default for Fonoster services, unify-config-placeholders); `${...}` anywhere
+     * else is an error.
+     */
+    interpolatePaths?: string[];
+    /** Old key path → new key path, reported as hints. */
+    movedKeys?: MovedKeys;
+    /** Env var prefixes of the old env-based config, reported as a warning. */
+    legacyEnvPrefixes?: string[];
+};
+/**
+ * Loads, interpolates and strictly validates a service's config file.
+ * Throws with the file path and the offending key path on any problem.
+ */
+declare function loadServiceConfig<S extends ZodTypeAny>(options: LoadServiceConfigOptions<S>): z.output<S>;
+export { loadServiceConfig, LoadServiceConfigOptions };

package/dist/config/loadServiceConfig.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadServiceConfig = loadServiceConfig;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const fs_1 = require("fs");
+const logger_1 = require("@fonoster/logger");
+const configHints_1 = require("./configHints");
+const interpolateEnv_1 = require("./interpolateEnv");
+const parseConfigFile_1 = require("./parseConfigFile");
+const resolveConfigFile_1 = require("./resolveConfigFile");
+const resolveSecretRefs_1 = require("./resolveSecretRefs");
+const strictDeep_1 = require("./strictDeep");
+const logger = (0, logger_1.getLogger)({ service: "common", filePath: __filename });
+/**
+ * One line per problem, each led by the key path:
+ * `smtp: unknown key "hsot"`, `features.auth.methods[1]: Invalid enum value ...`.
+ */
+function formatIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path
+            .map((segment, index) => typeof segment === "number"
+            ? `[${segment}]`
+            : index === 0
+                ? segment
+                : `.${segment}`)
+            .join("");
+        const where = path || "(root)";
+        if (issue.code === "unrecognized_keys") {
+            const keys = issue.keys.map((key) => `"${key}"`).join(", ");
+            return `${where}: unknown key${issue.keys.length > 1 ? "s" : ""} ${keys}`;
+        }
+        return `${where}: ${issue.message}`;
+    })
+        .join("; ");
+}
+/**
+ * Loads, interpolates and strictly validates a service's config file.
+ * Throws with the file path and the offending key path on any problem.
+ */
+function loadServiceConfig(options) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const { service, schema } = options;
+    const fileBase = (_a = options.fileBase) !== null && _a !== void 0 ? _a : service;
+    const argv = (_b = options.argv) !== null && _b !== void 0 ? _b : process.argv;
+    const env = (_c = options.env) !== null && _c !== void 0 ? _c : process.env;
+    const legacy = (0, configHints_1.findLegacyEnv)((_d = options.legacyEnvPrefixes) !== null && _d !== void 0 ? _d : [], env);
+    if (legacy.length > 0) {
+        logger.warn(`ignoring ${legacy.length} legacy environment variable(s); ${service} now reads its config file only: ${legacy.join(", ")}`);
+    }
+    const resolved = (0, resolveConfigFile_1.resolveConfigFile)(fileBase, argv, options.searchDirs);
+    const where = (_e = resolved.path) !== null && _e !== void 0 ? _e : "(built-in defaults)";
+    let raw = {};
+    if ("searched" in resolved) {
+        logger.warn(`no ${service} config file found (looked for ${resolved.searched.join(", ")}); using built-in defaults`);
+    }
+    else if (!(0, fs_1.existsSync)(resolved.path)) {
+        throw new Error(`unable to read ${service} config at ${resolved.path}: file not found`);
+    }
+    else {
+        try {
+            raw = (0, parseConfigFile_1.parseConfigFile)(resolved.path, (0, fs_1.readFileSync)(resolved.path, "utf8"));
+        }
+        catch (e) {
+            throw new Error(`unable to read ${service} config at ${resolved.path}: ${e.message}`);
+        }
+    }
+    // "$schema" points editors at the JSON Schema for autocomplete; it isn't config.
+    if (raw !== null && typeof raw === "object" && "$schema" in raw) {
+        const rest = Object.assign({}, raw);
+        delete rest.$schema;
+        raw = rest;
+    }
+    const moved = (0, configHints_1.findMovedKeys)(raw, (_f = options.movedKeys) !== null && _f !== void 0 ? _f : {});
+    if (moved.length > 0) {
+        throw new Error(`invalid ${service} config at ${where}: ${moved.join("; ")}`);
+    }
+    let interpolated;
+    try {
+        interpolated = (0, interpolateEnv_1.interpolateEnv)(raw, env, {
+            allowedPaths: (_g = options.interpolatePaths) !== null && _g !== void 0 ? _g : []
+        });
+    }
+    catch (e) {
+        throw new Error(`invalid ${service} config at ${where}: ${e.message}`);
+    }
+    // `secret://` references (D8): resolved here so the schema sees real values.
+    let withSecrets;
+    try {
+        withSecrets = (0, resolveSecretRefs_1.resolveSecretRefs)(interpolated, { env });
+    }
+    catch (e) {
+        throw new Error(`invalid ${service} config at ${where}: ${e.message}`);
+    }
+    const strictSchema = (0, strictDeep_1.strictDeep)(schema);
+    const result = strictSchema.safeParse(withSecrets);
+    if (!result.success) {
+        throw new Error(`invalid ${service} config at ${where}: ${formatIssues(result.error)}`);
+    }
+    if (resolved.path) {
+        logger.verbose(`loaded ${service} config`, { path: resolved.path });
+    }
+    return result.data;
+}

package/dist/config/logsSchema.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from "zod";
+/** The `logs` section shared by every Fonoster service's config file. */
+declare const logsSchema: z.ZodDefault<z.ZodEffects<z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<["error", "warn", "info", "http", "verbose", "debug", "silly"]>>;
+    format: z.ZodDefault<z.ZodEnum<["json", "text"]>>;
+    transport: z.ZodDefault<z.ZodEnum<["console", "fluent"]>>;
+    fluent: z.ZodOptional<z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodNumber>;
+        tagPrefix: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    }, {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    format?: "text" | "json";
+    level?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    fluent?: {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    };
+    transport?: "console" | "fluent";
+}, {
+    format?: "text" | "json";
+    level?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    fluent?: {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    };
+    transport?: "console" | "fluent";
+}>, {
+    format?: "text" | "json";
+    level?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    fluent?: {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    };
+    transport?: "console" | "fluent";
+}, {
+    format?: "text" | "json";
+    level?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    fluent?: {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    };
+    transport?: "console" | "fluent";
+}>>;
+type LogsConfig = z.infer<typeof logsSchema>;
+export { logsSchema, LogsConfig };

package/dist/config/logsSchema.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logsSchema = void 0;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const zod_1 = require("zod");
+/** The `logs` section shared by every Fonoster service's config file. */
+const logsSchema = zod_1.z
+    .object({
+    level: zod_1.z
+        .enum(["error", "warn", "info", "http", "verbose", "debug", "silly"])
+        .default("info"),
+    format: zod_1.z.enum(["json", "text"]).default("json"),
+    transport: zod_1.z.enum(["console", "fluent"]).default("console"),
+    fluent: zod_1.z
+        .object({
+        host: zod_1.z.string(),
+        port: zod_1.z.number().int().positive().default(24224),
+        tagPrefix: zod_1.z.string().default("fonoster-logs")
+    })
+        .optional()
+})
+    .superRefine((logs, ctx) => {
+    if (logs.transport === "fluent" && !logs.fluent) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["fluent"],
+            message: "required when transport is fluent"
+        });
+    }
+})
+    .default({});
+exports.logsSchema = logsSchema;

package/dist/config/natsConnection.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from "zod";
+/**
+ * A service's NATS connection settings (add-platform 4.1): the URL plus, when the server has
+ * per-service users, the service's user and password. The password is usually a `secret://`
+ * reference, resolved by the config loader like any other value.
+ */
+export declare const natsConnectionSchema: z.ZodObject<{
+    url: z.ZodString;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    url?: string;
+    user?: string;
+    password?: string;
+}, {
+    url?: string;
+    user?: string;
+    password?: string;
+}>;
+export type NatsConnectionConfig = z.infer<typeof natsConnectionSchema>;
+/** A NATS URL or full connection settings. */
+export type NatsTarget = string | NatsConnectionConfig;
+/**
+ * The inbox prefix of a NATS user: replies to its requests (and JetStream deliveries) arrive
+ * under `_INBOX_<user>.`, the only inbox its permissions let it subscribe to, so no service can
+ * read another's replies (nats-permissions/*.conf).
+ */
+export declare function natsInboxPrefix(user: string): string;
+/** nats.js `connect` options for a URL or a `{ url, user, password }` setting. */
+export declare function natsConnectOptions(nats: NatsTarget): {
+    servers: string;
+    user?: string;
+    pass?: string;
+    inboxPrefix?: string;
+};

package/dist/config/natsConnection.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.natsConnectionSchema = void 0;
+exports.natsInboxPrefix = natsInboxPrefix;
+exports.natsConnectOptions = natsConnectOptions;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const zod_1 = require("zod");
+/**
+ * A service's NATS connection settings (add-platform 4.1): the URL plus, when the server has
+ * per-service users, the service's user and password. The password is usually a `secret://`
+ * reference, resolved by the config loader like any other value.
+ */
+exports.natsConnectionSchema = zod_1.z
+    .object({
+    url: zod_1.z.string().min(1),
+    user: zod_1.z.string().min(1).optional(),
+    password: zod_1.z.string().min(1).optional()
+})
+    .strict();
+/**
+ * The inbox prefix of a NATS user: replies to its requests (and JetStream deliveries) arrive
+ * under `_INBOX_<user>.`, the only inbox its permissions let it subscribe to, so no service can
+ * read another's replies (nats-permissions/*.conf).
+ */
+function natsInboxPrefix(user) {
+    return `_INBOX_${user}`;
+}
+/** nats.js `connect` options for a URL or a `{ url, user, password }` setting. */
+function natsConnectOptions(nats) {
+    var _a;
+    if (typeof nats === "string")
+        return { servers: nats };
+    return nats.user
+        ? {
+            servers: nats.url,
+            user: nats.user,
+            pass: (_a = nats.password) !== null && _a !== void 0 ? _a : "",
+            inboxPrefix: natsInboxPrefix(nats.user)
+        }
+        : { servers: nats.url };
+}

package/dist/config/parseConfigFile.d.ts

@@ -0,0 +1,7 @@
+declare const CONFIG_EXTENSIONS: string[];
+/**
+ * Parses a config file's text. The extension picks the format: `.yaml`/`.yml`
+ * as YAML, `.json`/`.jsonc` as JSON with comments and trailing commas.
+ */
+declare function parseConfigFile(path: string, text: string): unknown;
+export { parseConfigFile, CONFIG_EXTENSIONS };