@kelpie/server 0.5.2 → 0.7.0

package/dist/lib/email.d.ts

@@ -5,15 +5,15 @@ import type { Logger } from './logger.ts';
  * and account-change notifications, nothing else. Kelpie never sends outreach
  * email.
  *
- * Roadmap decision 4: the provider is configured, never hardcoded. Core ships
- * the port and two providers, `log` and `smtp`. Both need no vendor account a
- * deployment doesn't already have, which is what keeps them in core rather than
- * a module, per `modules.md`'s split test. A provider that does need one
- * (Resend, Postmark, Mailtrap, SendGrid) is a commercial integration under that
- * same test and belongs in a module: it supplies its own `EmailSender` from its
- * own config, and an assembly's entry point wires it into `services.email` in
- * place of `createEmailSender`, the same way `kelpie-cloud/src/server.ts` wires
- * this one today.
+ * The assembly names one named provider in `kelpie.config.ts`'s
+ * `email.provider`. The module runtime resolves the name against a registry
+ * every module can contribute to via `context.provideEmailSender(name, sender)`.
+ * `'log'` is a built-in name the runtime always registers, so a bare install
+ * has something to point at. `'smtp'` is registered by the built-in
+ * `smtp-email` core module. Other names come from third-party provider modules
+ * (Resend, Postmark, SES) that follow the same registry pattern. Transport is
+ * arbitrary: the module builds one behind the `EmailSender` interface and
+ * hands it to core, which knows only how to `send`.
  */
 export interface EmailMessage {
     readonly to: string;
@@ -23,64 +23,16 @@ export interface EmailMessage {
 export interface EmailSender {
     send(message: EmailMessage): Promise<void>;
 }
-declare const smtpEmailConfigSchema: z.ZodObject<{
-    EMAIL_PROVIDER: z.ZodLiteral<"smtp">;
+export declare const emailConfigSchema: z.ZodObject<{
+    EMAIL_PROVIDER: z.ZodString;
     EMAIL_FROM: z.ZodString;
-    SMTP_HOST: z.ZodString;
-    SMTP_PORT: z.ZodCoercedNumber<unknown>;
-    SMTP_SECURE: z.ZodPipe<z.ZodEnum<{
-        false: "false";
-        true: "true";
-    }>, z.ZodTransform<boolean, "false" | "true">>;
-    SMTP_USER: z.ZodString;
-    SMTP_PASSWORD: z.ZodString;
 }, z.core.$strip>;
-export declare const emailConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    EMAIL_PROVIDER: z.ZodLiteral<"log">;
-    EMAIL_FROM: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    EMAIL_PROVIDER: z.ZodLiteral<"smtp">;
-    EMAIL_FROM: z.ZodString;
-    SMTP_HOST: z.ZodString;
-    SMTP_PORT: z.ZodCoercedNumber<unknown>;
-    SMTP_SECURE: z.ZodPipe<z.ZodEnum<{
-        false: "false";
-        true: "true";
-    }>, z.ZodTransform<boolean, "false" | "true">>;
-    SMTP_USER: z.ZodString;
-    SMTP_PASSWORD: z.ZodString;
-}, z.core.$strip>], "EMAIL_PROVIDER">;
 export type EmailConfig = z.infer<typeof emailConfigSchema>;
-export type SmtpEmailConfig = z.infer<typeof smtpEmailConfigSchema>;
 /**
- * Writes the message to the log instead of sending it. For self-hosted
- * development, where the reset link in the log is exactly what you want.
- *
- * This is a deliberate choice, not a fallback: `EMAIL_PROVIDER` has no default,
- * so nobody reaches this provider without naming it.
+ * Writes the message to the log instead of sending it. The registry default,
+ * swapped out for a real sender by picking a different provider name in
+ * `email.provider` (`'smtp'` for the built-in SMTP module, or any name a
+ * third-party provider module registers).
  */
 export declare function createLogEmailSender(logger: Logger, from: string): EmailSender;
-/**
- * What `createSmtpEmailSender` sends a message through. A real deployment gets
- * one backed by `nodemailer`; a test injects one that records calls, so the
- * sender is verifiable without a container running a real SMTP conversation.
- */
-export interface SmtpTransport {
-    sendMail(message: {
-        from: string;
-        to: string;
-        subject: string;
-        text: string;
-    }): Promise<unknown>;
-}
-/** Sends over SMTP. `transport` defaults to a real connection built from `config`. */
-export declare function createSmtpEmailSender(config: SmtpEmailConfig, logger: Logger, transport?: SmtpTransport): EmailSender;
-/**
- * Builds the configured sender.
- *
- * @throws Never. An unknown provider cannot reach here: the config schema is a
- *   discriminated union, so boot rejects it first.
- */
-export declare function createEmailSender(config: EmailConfig, logger: Logger): EmailSender;
-export {};
 //# sourceMappingURL=email.d.ts.map

package/dist/lib/email.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../src/lib/email.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C;AAOD,QAAA,MAAM,qBAAqB;;;;;;;;;;;iBAQzB,CAAA;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;qCAG5B,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAC3D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAa9E;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACjG;AAWD,sFAAsF;AACtF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,aAAiD,GAC3D,WAAW,CAiBb;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAOlF"}
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../src/lib/email.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C;AAED,eAAO,MAAM,iBAAiB;;;iBAS5B,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAa9E"}

package/dist/lib/email.js

@@ -1,34 +1,24 @@
-import nodemailer from 'nodemailer';
 import { z } from 'zod';
-import { describeThrown } from './errors.js';
-const logEmailConfigSchema = z.object({
-    EMAIL_PROVIDER: z.literal('log'),
+export const emailConfigSchema = z.object({
+    /**
+     * The named provider `registerModules` resolves against its registry. `'log'`
+     * is a built-in, always present. Any other name needs a module that
+     * registered it via `context.provideEmailSender(name, sender)`. Free-string
+     * so a self-hoster can add a module core has never heard of.
+     */
+    EMAIL_PROVIDER: z.string().min(1),
     EMAIL_FROM: z.string().min(1),
 });
-const smtpEmailConfigSchema = z.object({
-    EMAIL_PROVIDER: z.literal('smtp'),
-    EMAIL_FROM: z.string().min(1),
-    SMTP_HOST: z.string().min(1),
-    SMTP_PORT: z.coerce.number().int().positive().max(65535),
-    SMTP_SECURE: z.enum(['true', 'false']).transform((value) => value === 'true'),
-    SMTP_USER: z.string().min(1),
-    SMTP_PASSWORD: z.string().min(1),
-});
-export const emailConfigSchema = z.discriminatedUnion('EMAIL_PROVIDER', [
-    logEmailConfigSchema,
-    smtpEmailConfigSchema,
-]);
 /**
- * Writes the message to the log instead of sending it. For self-hosted
- * development, where the reset link in the log is exactly what you want.
- *
- * This is a deliberate choice, not a fallback: `EMAIL_PROVIDER` has no default,
- * so nobody reaches this provider without naming it.
+ * Writes the message to the log instead of sending it. The registry default,
+ * swapped out for a real sender by picking a different provider name in
+ * `email.provider` (`'smtp'` for the built-in SMTP module, or any name a
+ * third-party provider module registers).
  */
 export function createLogEmailSender(logger, from) {
     return {
         send(message) {
-            logger.info('email not sent: provider is "log"', {
+            logger.info('email not sent: no provider module registered', {
                 from,
                 to: message.to,
                 subject: message.subject,
@@ -38,46 +28,4 @@ export function createLogEmailSender(logger, from) {
         },
     };
 }
-function createNodemailerTransport(config) {
-    return nodemailer.createTransport({
-        host: config.SMTP_HOST,
-        port: config.SMTP_PORT,
-        secure: config.SMTP_SECURE,
-        auth: { user: config.SMTP_USER, pass: config.SMTP_PASSWORD },
-    });
-}
-/** Sends over SMTP. `transport` defaults to a real connection built from `config`. */
-export function createSmtpEmailSender(config, logger, transport = createNodemailerTransport(config)) {
-    return {
-        async send(message) {
-            try {
-                await transport.sendMail({
-                    from: config.EMAIL_FROM,
-                    to: message.to,
-                    subject: message.subject,
-                    text: message.body,
-                });
-            }
-            catch (cause) {
-                const reason = describeThrown(cause);
-                logger.error('smtp send failed', { to: message.to, reason });
-                throw new Error(`Failed to send email to ${message.to} over SMTP: ${reason}`, { cause });
-            }
-        },
-    };
-}
-/**
- * Builds the configured sender.
- *
- * @throws Never. An unknown provider cannot reach here: the config schema is a
- *   discriminated union, so boot rejects it first.
- */
-export function createEmailSender(config, logger) {
-    switch (config.EMAIL_PROVIDER) {
-        case 'log':
-            return createLogEmailSender(logger, config.EMAIL_FROM);
-        case 'smtp':
-            return createSmtpEmailSender(config, logger);
-    }
-}
 //# sourceMappingURL=email.js.map

package/dist/lib/email.js.map

@@ -1 +1 @@
-{"version":3,"file":"email.js","sourceRoot":"","sources":["../../src/lib/email.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../../src/lib/email.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AA8BvB,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC9B,CAAC,CAAA;AAIF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,IAAY;IAC/D,OAAO;QACL,IAAI,CAAC,OAAO;YACV,MAAM,CAAC,IAAI,CAAC,+CAA+C,EAAE;gBAC3D,IAAI;gBACJ,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,IAAI,EAAE,OAAO,CAAC,IAAI;aACnB,CAAC,CAAA;YAEF,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/lib/fromEnv.d.ts

@@ -0,0 +1,60 @@
+import type { ZodType } from 'zod';
+import type { Environment } from './config.ts';
+/**
+ * A marker a `kelpie.config.ts` file uses to say "read this leaf from the
+ * environment." The assembly's config file is the shape and the defaults;
+ * `fromEnv` marks the leaves a deployment may override without a code change.
+ *
+ * Every marker names an env var, the Zod schema that parses it, and optionally
+ * a default. Without a default the marker is required: the env var must be set,
+ * or boot fails with the other configuration problems.
+ *
+ * The resolver walks the config object, replaces each marker with the parsed
+ * value, and returns the fully-resolved object. Nothing in the app reads
+ * `process.env` for these fields after boot.
+ */
+declare const FROM_ENV_MARKER: unique symbol;
+export interface FromEnvMarker<T> {
+    readonly [FROM_ENV_MARKER]: true;
+    readonly envKey: string;
+    readonly schema: ZodType<T>;
+    readonly defaultValue: T | undefined;
+    readonly hasDefault: boolean;
+}
+/** A leaf in the config file: either a literal already-typed value, or a marker. */
+export type ConfigValue<T> = T | FromEnvMarker<T>;
+export declare function fromEnv<T>(envKey: string, schema: ZodType<T>): FromEnvMarker<T>;
+export declare function fromEnv<T>(envKey: string, schema: ZodType<T>, defaultValue: T): FromEnvMarker<T>;
+export declare function isFromEnvMarker(value: unknown): value is FromEnvMarker<unknown>;
+/** One problem discovered while resolving markers. Path is the dotted field. */
+export interface FromEnvProblem {
+    readonly path: string;
+    readonly message: string;
+}
+export interface ResolveResult<T> {
+    readonly value: T | undefined;
+    readonly problems: readonly FromEnvProblem[];
+}
+/**
+ * Resolves one marker against an environment.
+ *
+ * Missing and no default: one required problem.
+ * Missing with default: the default, unvalidated. A hardcoded default is
+ * trusted because the developer wrote it in the assembly file.
+ * Present: parsed through the marker's schema. Parse failures become problems.
+ */
+export declare function resolveMarker<T>(marker: FromEnvMarker<T>, environment: Environment, path: string): ResolveResult<T>;
+/**
+ * Walks any value, replacing every `FromEnvMarker` with its resolved value.
+ * Objects and arrays are walked recursively; other values pass through.
+ *
+ * Collects problems from every marker rather than throwing at the first one,
+ * so a self-hoster fixes their environment once rather than a variable at a
+ * time.
+ */
+export declare function resolveMarkers(input: unknown, environment: Environment, path?: string): {
+    readonly value: unknown;
+    readonly problems: readonly FromEnvProblem[];
+};
+export {};
+//# sourceMappingURL=fromEnv.d.ts.map

package/dist/lib/fromEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fromEnv.d.ts","sourceRoot":"","sources":["../../src/lib/fromEnv.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAElC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;;;;;;GAYG;AAEH,QAAA,MAAM,eAAe,eAA+B,CAAA;AAEpD,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B;AAED,oFAAoF;AACpF,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;AAEjD,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;AAChF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;AAajG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,CAE/E;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CA2BnH;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,WAAW,EACxB,IAAI,SAAK,GACR;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;CAAE,CAiC3E"}

package/dist/lib/fromEnv.js

@@ -0,0 +1,94 @@
+/**
+ * A marker a `kelpie.config.ts` file uses to say "read this leaf from the
+ * environment." The assembly's config file is the shape and the defaults;
+ * `fromEnv` marks the leaves a deployment may override without a code change.
+ *
+ * Every marker names an env var, the Zod schema that parses it, and optionally
+ * a default. Without a default the marker is required: the env var must be set,
+ * or boot fails with the other configuration problems.
+ *
+ * The resolver walks the config object, replaces each marker with the parsed
+ * value, and returns the fully-resolved object. Nothing in the app reads
+ * `process.env` for these fields after boot.
+ */
+const FROM_ENV_MARKER = Symbol.for('kelpie.fromEnv');
+export function fromEnv(envKey, schema, defaultValue) {
+    const hasDefault = arguments.length >= 3;
+    return {
+        [FROM_ENV_MARKER]: true,
+        envKey,
+        schema,
+        defaultValue: hasDefault ? defaultValue : undefined,
+        hasDefault,
+    };
+}
+export function isFromEnvMarker(value) {
+    return typeof value === 'object' && value !== null && value[FROM_ENV_MARKER] === true;
+}
+/**
+ * Resolves one marker against an environment.
+ *
+ * Missing and no default: one required problem.
+ * Missing with default: the default, unvalidated. A hardcoded default is
+ * trusted because the developer wrote it in the assembly file.
+ * Present: parsed through the marker's schema. Parse failures become problems.
+ */
+export function resolveMarker(marker, environment, path) {
+    const raw = environment[marker.envKey];
+    if (raw === undefined) {
+        if (marker.hasDefault) {
+            return { value: marker.defaultValue, problems: [] };
+        }
+        return {
+            value: undefined,
+            problems: [{ path, message: `${marker.envKey} is required` }],
+        };
+    }
+    const result = marker.schema.safeParse(raw);
+    if (!result.success) {
+        return {
+            value: undefined,
+            problems: result.error.issues.map((issue) => ({
+                path,
+                message: `${marker.envKey}: ${issue.message}`,
+            })),
+        };
+    }
+    return { value: result.data, problems: [] };
+}
+/**
+ * Walks any value, replacing every `FromEnvMarker` with its resolved value.
+ * Objects and arrays are walked recursively; other values pass through.
+ *
+ * Collects problems from every marker rather than throwing at the first one,
+ * so a self-hoster fixes their environment once rather than a variable at a
+ * time.
+ */
+export function resolveMarkers(input, environment, path = '') {
+    if (isFromEnvMarker(input)) {
+        return resolveMarker(input, environment, path);
+    }
+    if (Array.isArray(input)) {
+        const problems = [];
+        const value = input.map((item, index) => {
+            const childPath = `${path}[${String(index)}]`;
+            const result = resolveMarkers(item, environment, childPath);
+            problems.push(...result.problems);
+            return result.value;
+        });
+        return { value, problems };
+    }
+    if (typeof input === 'object' && input !== null) {
+        const problems = [];
+        const value = {};
+        for (const [key, child] of Object.entries(input)) {
+            const childPath = path.length > 0 ? `${path}.${key}` : key;
+            const result = resolveMarkers(child, environment, childPath);
+            problems.push(...result.problems);
+            value[key] = result.value;
+        }
+        return { value, problems };
+    }
+    return { value: input, problems: [] };
+}
+//# sourceMappingURL=fromEnv.js.map

package/dist/lib/fromEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fromEnv.js","sourceRoot":"","sources":["../../src/lib/fromEnv.ts"],"names":[],"mappings":"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"}

package/dist/lib/ids.d.ts

@@ -50,6 +50,12 @@ export declare const idPrefixes: {
      * a bucket is bookkeeping the rate limiter owns, not a resource with routes.
      */
     readonly rateLimitBucket: 'rl';
+    /**
+     * One published domain event. Stamped on the envelope so downstream consumers
+     * (webhooks, MCP subscribers, an eventual outbox) have a stable idempotency
+     * key. Not persisted by core.
+     */
+    readonly event: 'ev';
 };
 export type ObjectKind = keyof typeof idPrefixes;
 export type IdFactory = (kind: ObjectKind) => string;

package/dist/lib/ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,UAAU;aACrB,SAAS,EAAE,IAAI;aACf,IAAI,EAAE,KAAK;aACX,OAAO,EAAE,KAAK;aACd,kBAAkB,EAAE,KAAK;IACzB,wFAAwF;aACxF,sBAAsB,EAAE,KAAK;aAC7B,UAAU,EAAE,KAAK;aACjB,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,OAAO,EAAE,KAAK;aACd,QAAQ,EAAE,KAAK;aACf,aAAa,EAAE,OAAO;aACtB,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,KAAK;aAClB,WAAW,EAAE,KAAK;aAClB,KAAK,EAAE,KAAK;aACZ,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;aAChB,QAAQ,EAAE,KAAK;aACf,IAAI,EAAE,MAAM;aACZ,QAAQ,EAAE,KAAK;aACf,YAAY,EAAE,IAAI;aAClB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,IAAI;aACf,cAAc,EAAE,KAAK;aACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;aAC9E,eAAe,EAAE,KAAK;aACtB,iBAAiB,EAAE,IAAI;aACvB,QAAQ,EAAE,KAAK;aACf,SAAS,EAAE,KAAK;IAChB,6FAA6F;aAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;aACH,cAAc,EAAE,MAAM;IACtB;;;OAGG;aACH,eAAe,EAAE,IAAI;CACb,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAA;AAEhD,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAA;AAEpD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,GAAE,MAAM,MAAa,GAAG,SAAS,CAE5E"}
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,UAAU;aACrB,SAAS,EAAE,IAAI;aACf,IAAI,EAAE,KAAK;aACX,OAAO,EAAE,KAAK;aACd,kBAAkB,EAAE,KAAK;IACzB,wFAAwF;aACxF,sBAAsB,EAAE,KAAK;aAC7B,UAAU,EAAE,KAAK;aACjB,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,OAAO,EAAE,KAAK;aACd,QAAQ,EAAE,KAAK;aACf,aAAa,EAAE,OAAO;aACtB,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,KAAK;aAClB,WAAW,EAAE,KAAK;aAClB,KAAK,EAAE,KAAK;aACZ,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;aAChB,QAAQ,EAAE,KAAK;aACf,IAAI,EAAE,MAAM;aACZ,QAAQ,EAAE,KAAK;aACf,YAAY,EAAE,IAAI;aAClB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,IAAI;aACf,cAAc,EAAE,KAAK;aACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;aAC9E,eAAe,EAAE,KAAK;aACtB,iBAAiB,EAAE,IAAI;aACvB,QAAQ,EAAE,KAAK;aACf,SAAS,EAAE,KAAK;IAChB,6FAA6F;aAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;aACH,cAAc,EAAE,MAAM;IACtB;;;OAGG;aACH,eAAe,EAAE,IAAI;IACrB;;;;OAIG;aACH,KAAK,EAAE,IAAI;CACH,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAA;AAEhD,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAA;AAEpD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,GAAE,MAAM,MAAa,GAAG,SAAS,CAE5E"}

package/dist/lib/ids.js

@@ -51,6 +51,12 @@ export const idPrefixes = {
      * a bucket is bookkeeping the rate limiter owns, not a resource with routes.
      */
     rateLimitBucket: 'rl',
+    /**
+     * One published domain event. Stamped on the envelope so downstream consumers
+     * (webhooks, MCP subscribers, an eventual outbox) have a stable idempotency
+     * key. Not persisted by core.
+     */
+    event: 'ev',
 };
 /**
  * Builds the id factory. The ULID generator is injected so tests can pin ids;

package/dist/lib/ids.js.map

@@ -1 +1 @@
-{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,SAAS,EAAE,IAAI;IACf,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,KAAK;IACd,kBAAkB,EAAE,KAAK;IACzB,wFAAwF;IACxF,sBAAsB,EAAE,KAAK;IAC7B,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,KAAK;IACf,aAAa,EAAE,OAAO;IACtB,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,KAAK,EAAE,KAAK;IACZ,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,MAAM;IACjB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,KAAK;IACf,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,IAAI;IAClB,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,KAAK;IACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;IAC9E,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,IAAI;IACvB,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,6FAA6F;IAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;IACH,cAAc,EAAE,MAAM;IACtB;;;OAGG;IACH,eAAe,EAAE,IAAI;CACb,CAAA;AAMV;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,YAAY,GAAiB,IAAI;IAC/D,OAAO,CAAC,IAAgB,EAAU,EAAE,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,YAAY,EAAE,EAAE,CAAA;AAC9E,CAAC"}
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,SAAS,EAAE,IAAI;IACf,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,KAAK;IACd,kBAAkB,EAAE,KAAK;IACzB,wFAAwF;IACxF,sBAAsB,EAAE,KAAK;IAC7B,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,KAAK;IACf,aAAa,EAAE,OAAO;IACtB,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,KAAK,EAAE,KAAK;IACZ,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,MAAM;IACjB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,KAAK;IACf,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,IAAI;IAClB,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,KAAK;IACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;IAC9E,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,IAAI;IACvB,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,6FAA6F;IAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;IACH,cAAc,EAAE,MAAM;IACtB;;;OAGG;IACH,eAAe,EAAE,IAAI;IACrB;;;;OAIG;IACH,KAAK,EAAE,IAAI;CACH,CAAA;AAMV;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,YAAY,GAAiB,IAAI;IAC/D,OAAO,CAAC,IAAgB,EAAU,EAAE,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,YAAY,EAAE,EAAE,CAAA;AAC9E,CAAC"}

package/dist/lib/kelpieConfigFile.d.ts

@@ -0,0 +1,129 @@
+import type { KelpieModule } from '../runtime/module.ts';
+import { type Environment, type KelpieConfig, type LogLevel, type RuntimeMode } from './config.ts';
+import { type ConfigValue } from './fromEnv.ts';
+import type { LoggingDestination } from './logger.ts';
+/**
+ * The shape a `kelpie.config.ts` file declares.
+ *
+ * Every leaf is either a literal value the assembly commits to git, or a
+ * `fromEnv(...)` marker the deployment fills in. The resolver walks this
+ * object, replaces markers with parsed values, and returns a fully-populated
+ * `KelpieConfig`.
+ *
+ * The file is the map. `fromEnv(...)` marks the leaves a deployment overrides.
+ * Nothing in the app reads `process.env` for these fields after boot.
+ */
+export interface KelpieConfigInput {
+    readonly runtimeMode: ConfigValue<RuntimeMode>;
+    readonly port: ConfigValue<number>;
+    readonly databaseUrl: ConfigValue<string>;
+    readonly logging: LoggingInput;
+    /** Optional; unset in development, set to the built web bundle in a deployment. */
+    readonly webBundleDirectory?: ConfigValue<string | undefined>;
+    /** Optional; unset in development, set to the deploy-time module override file. */
+    readonly moduleConfigPath?: ConfigValue<string | undefined>;
+    /**
+     * Human-readable name of this deployment ("dev", "demo", "cloud"). Optional.
+     * Read by the browser through `GET /v1/public/config` so a non-production UI
+     * can name the site it is on. Ignored when `runtimeMode` is `production`.
+     */
+    readonly siteName?: ConfigValue<string | undefined>;
+    /** Optional; defaults to 0 (no proxy in front). */
+    readonly trustedProxyHopCount?: ConfigValue<number>;
+    /**
+     * The deployment's base URL. Every emailed link (password reset, email
+     * verification, invite) is built from it. Required by the workspace and auth
+     * modules. Optional here so an older assembly can omit it and let those
+     * modules fall back to the `context.config(appUrlConfigSchema)` path.
+     */
+    readonly appBaseUrl?: ConfigValue<string>;
+    /**
+     * Keys that seal stored secrets (webhook signing secrets, agent-task auth
+     * headers). Required by the webhooks and agent-tasks modules. Optional here
+     * for the same reason `appBaseUrl` is.
+     */
+    readonly secretEncryption?: SecretEncryptionInput;
+    readonly email: EmailInput;
+    /** Optional; each unset field falls back to the same defaults `loadConfig` used. */
+    readonly rateLimit?: RateLimitInput;
+    /**
+     * Env-keyed values the assembly can lock in code, or defer to the
+     * environment. Modules read this through `context.config(schema)`; each
+     * module's own Zod schema still names the keys and validates them.
+     *
+     * A key present here overrides the same key in `process.env`. A key absent
+     * here falls through to `process.env` unchanged, so the section is a
+     * progressive migration: lock what you want to lock, leave the rest.
+     *
+     * Literal: `SECRET_ENCRYPTION_KEY: 'a-committed-key'` (don't do this for
+     * secrets — the point is you can, if the value is not a secret).
+     * Marker: `SECRET_ENCRYPTION_KEY: fromEnv('SECRET_ENCRYPTION_KEY', z.string())`
+     * defers to the environment, same as today.
+     */
+    readonly env?: Readonly<Record<string, ConfigValue<string | undefined>>>;
+    /** The module list the assembly composes. Same shape it had before. */
+    readonly modules: readonly KelpieModule[];
+}
+/**
+ * The `logging` sub-tree of the assembly config.
+ *
+ * `level` is the minimum severity to emit. `destinations` is the ordered list
+ * of destinations each line writes to; stdout is the default entry in the
+ * template assembly, and a self-hoster adds another by extending
+ * `LoggingDestination` in `@kelpie/server` and putting a matching entry here.
+ */
+export interface LoggingInput {
+    readonly level: ConfigValue<LogLevel>;
+    readonly destinations: readonly LoggingDestination[];
+}
+/**
+ * The `email` sub-tree of the assembly config.
+ *
+ * `provider` names one entry in the runtime's provider registry. `'log'` is a
+ * built-in the runtime always registers; `'smtp'` is registered by the
+ * built-in `smtp-email` core module; third-party provider modules register
+ * their own names (an API-based provider might register `'resend'` or
+ * `'postmark'`, and so on). Free-string so a self-hoster can install a
+ * module core has never heard of.
+ *
+ * `from` is the address on every outgoing message. Provider-specific config
+ * (SMTP host and credentials, an API key) belongs to the provider module,
+ * which reads it through `context.config(...)`; putting it here would tie the
+ * assembly config to a single transport.
+ */
+export interface EmailInput {
+    readonly provider: ConfigValue<string>;
+    readonly from: ConfigValue<string>;
+}
+export interface SecretEncryptionInput {
+    readonly key: ConfigValue<string>;
+    /** Absent (or blank) is normal; only set while rotating away from an older key. */
+    readonly previousKey?: ConfigValue<string | undefined>;
+}
+export interface RateLimitBudgetInput {
+    readonly limit?: ConfigValue<number>;
+    readonly windowSeconds?: ConfigValue<number>;
+}
+export interface RateLimitInput {
+    readonly forms?: RateLimitBudgetInput;
+    readonly auth?: RateLimitBudgetInput;
+    readonly loginAccount?: RateLimitBudgetInput;
+    readonly api?: RateLimitBudgetInput;
+}
+/**
+ * Identity helper for the assembly's config file. It exists for the type-check
+ * only: `defineKelpieConfig({...})` makes TypeScript check the object against
+ * `KelpieConfigInput` at the call site, so a wrong-shape field is caught in
+ * the assembly rather than at boot.
+ */
+export declare function defineKelpieConfig(input: KelpieConfigInput): KelpieConfigInput;
+/**
+ * Resolves an assembly's config against an environment.
+ *
+ * Every `fromEnv` marker is resolved. Missing required variables and parse
+ * failures are collected together, so a self-hoster fixes them in one pass.
+ *
+ * @throws ConfigurationError listing every problem.
+ */
+export declare function resolveKelpieConfig(input: KelpieConfigInput, environment: Environment): KelpieConfig;
+//# sourceMappingURL=kelpieConfigFile.d.ts.map

package/dist/lib/kelpieConfigFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kelpieConfigFile.d.ts","sourceRoot":"","sources":["../../src/lib/kelpieConfigFile.ts"],"names":[],"mappings":"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"}