@sockethub/server 5.0.0-alpha.15 → 5.0.0-alpha.17

package/dist/config-schema.d.ts

@@ -0,0 +1,58 @@
+import convict from "convict";
+/**
+ * The convict configuration schema, derived from the canonical JSON schema in
+ * `@sockethub/schemas` so defaults, types and enums have a single source of
+ * truth. This module only layers on the server-specific concerns the JSON
+ * schema cannot express: environment variable and command-line argument
+ * bindings, and convict format refinements ("nat", "port").
+ */
+type JsonSchemaNode = {
+    type?: string | Array<string>;
+    enum?: Array<unknown>;
+    default?: unknown;
+    description?: string;
+    properties?: Record<string, JsonSchemaNode>;
+};
+type OverlayEntry = {
+    /** Convict format override (e.g. "nat", "port", "*"). */
+    format?: unknown;
+    /** Environment variable bound to this key. */
+    env?: string;
+    /**
+     * Treat an empty-string value of `env` as unset so it falls back to the
+     * config file / default, preserving the historical `process.env.X || ...`
+     * behavior (convict would otherwise apply the empty string as an
+     * override). Deliberately NOT set for SOCKETHUB_CORS_ORIGIN, where an
+     * empty string must stay applied so CORS fails closed.
+     */
+    emptyEnvIsUnset?: boolean;
+    /** Command-line argument bound to this key. */
+    arg?: string;
+    /**
+     * Treat this object node as a single convict leaf (validated as a whole
+     * by the JSON schema pass) instead of recursing into its properties.
+     */
+    leaf?: boolean;
+    /** Default for leaves the JSON schema declares no default for. */
+    default?: unknown;
+};
+/**
+ * Build the convict schema definition from a JSON schema plus a server
+ * overlay. Exported for tests; production code uses {@link buildSchema}.
+ * Throws when an overlay entry references a path the JSON schema does not
+ * declare, or when a leaf ends up without a default.
+ */
+export declare function buildConvictDefinition(jsonSchema: JsonSchemaNode, overlays: Record<string, OverlayEntry>): Record<string, unknown>;
+export declare function buildSchema(): convict.Config<Record<string, unknown>>;
+/**
+ * Environment variables where an empty-string value means "unset" rather
+ * than an override (historical `process.env.X || <config>` semantics).
+ */
+export declare const EMPTY_ENV_IS_UNSET_VARS: ReadonlyArray<string>;
+/**
+ * The fully materialized default configuration tree, straight from the JSON
+ * schema (no environment or command-line overrides applied). The `$schema`
+ * key is omitted; callers stamp their own reference.
+ */
+export declare function getDefaultConfig(): Record<string, unknown>;
+export {};