@happyvertical/smrt-config 0.51.31 → 0.51.33

package/dist/export.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Config export utilities for static site generation
+ *
+ * These utilities enable exporting database-backed agent configurations
+ * to static files for SSG sites.
+ *
+ * @module
+ */
+/**
+ * Deep-clone a config object, removing every key that looks like a secret.
+ *
+ * Keys are tested (case-insensitively, across camelCase / snake_case / kebab /
+ * UPPER variants) against {@link SECRET_PATTERNS}, which cover secrets such as
+ * `apiKey`/`api_key`, `password`, `secret`, `token`, `credential`, `private`,
+ * `auth`/`authorization`/`oauth`, `accessKey`, `signingKey`, `encryptionKey`,
+ * `connectionString`, and `dbUrl`. The policy biases toward over-redaction
+ * because these exports are typically published as static, publicly served
+ * assets — see {@link SECRET_PATTERNS} for the full rationale.
+ *
+ * Nested objects are recursively sanitized; arrays are mapped element-by-element.
+ * `number` / `boolean` primitives pass through unchanged; `string` values are
+ * additionally run through value-level redaction that masks credentials embedded
+ * in a URL (`scheme://user:pass@host` → `scheme://***@host`) as well as
+ * high-confidence secret-token shapes pasted into otherwise-benign keys
+ * (OpenAI/Anthropic `sk-...`, AWS `AKIA...` access key IDs, GitHub/Slack/Google
+ * tokens, `Bearer ...` headers, and PEM private-key blocks) — catching secrets
+ * stored under a benign key the key-based patterns don't match.
+ *
+ * Own `__proto__` / `constructor` / `prototype` keys are dropped to prevent the
+ * cloned result's prototype from being reassigned via the `__proto__` setter.
+ *
+ * This function is called automatically by {@link exportConfig} unless
+ * `includeSecrets: true` is passed.
+ *
+ * @param config - Value to sanitize. Accepts any JSON-serializable structure.
+ * @returns A new value with all secret keys omitted. `null` / `undefined` are
+ *   returned as-is.
+ *
+ * @example
+ * ```ts
+ * const sanitized = sanitizeConfig({
+ *   apiEndpoint: 'https://api.example.com',
+ *   apiKey: 'sk-secret-123',
+ *   nested: { password: 'hunter2', name: 'test' },
+ * });
+ * // => { apiEndpoint: 'https://api.example.com', nested: { name: 'test' } }
+ * ```
+ *
+ * @see {@link exportConfig}
+ */
+export declare function sanitizeConfig(config: unknown): unknown;
+/**
+ * Options accepted by {@link exportConfig}.
+ */
+export interface ExportConfigOptions {
+    /**
+     * Include secrets in the export (use with caution!)
+     * @default false
+     */
+    includeSecrets?: boolean;
+    /**
+     * Output format
+     * - 'json': Plain JSON format
+     * - 'js': ES module format (export default)
+     * @default 'json'
+     */
+    format?: 'json' | 'js';
+    /**
+     * Number of spaces for indentation
+     * @default 2
+     */
+    indent?: number;
+}
+/**
+ * Serialize a configuration object to a formatted string for SSG file output.
+ *
+ * By default, {@link sanitizeConfig} is applied before serialization to strip
+ * any keys that match secret patterns (API keys, passwords, tokens, etc.).
+ * Pass `includeSecrets: true` only in secured server-side contexts.
+ *
+ * @param config - Configuration object to export. Any JSON-serializable value.
+ * @param options - Format, indentation, and secret-inclusion options.
+ * @returns A JSON string, or an ES module string (`export default {...};\n`)
+ *   when `format: 'js'`.
+ *
+ * @example
+ * ```ts
+ * // Write a sanitized JSON export file for SSG
+ * const json = exportConfig(agentConfig);
+ * await fs.writeFile('./public/config.json', json);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // ES module format (importable via `import config from './config.js'`)
+ * const js = exportConfig(agentConfig, { format: 'js' });
+ * ```
+ *
+ * @see {@link sanitizeConfig}
+ * @see {@link parseExportedConfig}
+ * @see {@link ExportConfigOptions}
+ */
+export declare function exportConfig(config: unknown, options?: ExportConfigOptions): string;
+/**
+ * Parse a config string previously produced by {@link exportConfig} back into
+ * a plain JavaScript object.
+ *
+ * Handles both output formats:
+ * - **JSON** — standard `JSON.parse`.
+ * - **JS module** — strips the `export default` prefix and trailing semicolon
+ *   before parsing as JSON.
+ *
+ * Throws a `SyntaxError` if the content is not valid JSON after stripping.
+ *
+ * @param content - Exported config string (`'json'` or `'js'` format).
+ * @returns Parsed configuration value.
+ *
+ * @example
+ * ```ts
+ * const raw = await fs.readFile('./smrt.exported.json', 'utf8');
+ * const config = parseExportedConfig(raw);
+ * ```
+ *
+ * @see {@link exportConfig}
+ * @see {@link mergeExportedConfig}
+ */
+export declare function parseExportedConfig(content: string): unknown;
+/**
+ * Shallow-merge an exported (DB-backed) config into a base (file-backed) config.
+ *
+ * Object values are deep-merged recursively. Primitive values and arrays from
+ * `exportedConfig` replace their counterparts in `baseConfig`. This is a
+ * one-level-smarter spread that lets file-based env overrides win when placed
+ * after the spread.
+ *
+ * Intended for the SSG pattern where an agent exports its runtime config to a
+ * static JSON file and `smrt.config.js` imports it as a base:
+ *
+ * @example
+ * ```js
+ * // smrt.config.js
+ * import exported from './smrt.exported.json' with { type: 'json' };
+ *
+ * export default defineConfig({
+ *   modules: {
+ *     praeco: mergeExportedConfig(exported, {
+ *       apiEndpoint: process.env.API_URL, // env override wins
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @param baseConfig - Lower-priority base (typically from the DB export file).
+ * @param exportedConfig - Higher-priority overrides (typically env / file-based).
+ * @returns A new merged object of type `T`.
+ *
+ * @see {@link exportConfig}
+ * @see {@link parseExportedConfig}
+ */
+export declare function mergeExportedConfig<T extends Record<string, unknown>>(baseConfig: T, exportedConfig: Partial<T>): T;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAyCvD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAaR;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAY5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,UAAU,EAAE,CAAC,EACb,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC,GACzB,CAAC,CA6BH"}