@mettlecast/domain-runtime 0.2.75 → 0.2.77

package/dist/ctx/context.d.ts

@@ -7,6 +7,7 @@ import type { AuditContext } from '../runtime/audit.js';
 import type { DomainStoreContext } from './store.js';
 import type { DomainFilesContext } from './files.js';
 import type { CognitoContext } from './cognito.js';
+import type { SesContext } from './ses.js';
 /**
  * The unified domain context injected into every handler.
  * All fields are always populated by the runtime; no field is ever null.
@@ -50,6 +51,8 @@ export interface DomainContext {
     files: DomainFilesContext;
     /** Cognito control-plane client (Admin* operations). Noop when no user pool is configured. */
     cognito: CognitoContext;
+    /** SES email-sending client. Noop when SES_FROM_EMAIL is not set. */
+    ses: SesContext;
     /** URL path parameters from the incoming request, excluding tenantId (e.g. { tableName: 'users' }). */
     pathParams: Record<string, string>;
 }

package/dist/ctx/index.d.ts

@@ -5,3 +5,4 @@ export type { DomainContext } from './context.js';
 export type { DomainStoreContext, StoreQueryOptions, StoreQueryResult } from './store.js';
 export type { DomainFilesContext, FilesPutOptions, FilesListResult } from './files.js';
 export type { CognitoContext } from './cognito.js';
+export type { SesContext } from './ses.js';

package/dist/ctx/ses.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SES email-sending context. Automatically scoped to the configured
+ * sending identity — domain code never passes `Source`, region, or
+ * the SES client configuration.
+ *
+ * The runtime creates this when `SES_FROM_EMAIL` is set in the
+ * Lambda environment. Domain code accesses it via `ctx.ses`.
+ */
+export interface SesContext {
+    /**
+     * Send an email via SES. The runtime manages the SES client,
+     * region, and sending identity — domain code only provides
+     * the email content.
+     *
+     * @param params.to - Recipient email address(es).
+     * @param params.subject - Email subject line.
+     * @param params.htmlBody - HTML body content.
+     * @param params.textBody - Plain-text fallback body.
+     * @param params.from - Optional sender override (defaults to env SES_FROM_EMAIL).
+     * @param params.replyTo - Optional reply-to address(es).
+     * @returns The SES MessageId for the sent email.
+     */
+    sendEmail(params: {
+        to: string | string[];
+        subject: string;
+        htmlBody?: string;
+        textBody?: string;
+        from?: string;
+        replyTo?: string | string[];
+    }): Promise<{
+        messageId: string;
+    }>;
+}

package/dist/ctx/ses.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export type * from './ctx/index.js';
 export * from './primitives/index.js';
 export * from './schema/index.js';
 export * from './runtime/index.js';
+export { initOtel } from './runtime/tracer.js';

package/dist/index.js

@@ -4,3 +4,6 @@ export * from './primitives/index.js';
 export * from './schema/index.js';
 // Runtime implementations
 export * from './runtime/index.js';
+// Explicit re-export — `export *` wildcard doesn't reliably surface this
+// for TS module resolution in all configurations.
+export { initOtel } from './runtime/tracer.js';

package/dist/runtime/hydrate.d.ts

@@ -7,6 +7,7 @@ import type { IntegrationDefinition } from '../primitives/integration.js';
 import type { DomainStoreContext } from '../ctx/store.js';
 import type { DomainFilesContext } from '../ctx/files.js';
 import type { CognitoContext } from '../ctx/cognito.js';
+import type { SesContext } from '../ctx/ses.js';
 import type { ActionRegistry } from './actions.js';
 /**
  * Full options for hydrateCtx. All fields are optional — defaults are used for
@@ -113,6 +114,8 @@ export interface HydrateOptions {
     pathParams?: Record<string, string>;
     /** Override the Cognito context. If omitted, createCognito() is used (reads COGNITO_USER_POOL_ID from env). */
     cognito?: CognitoContext;
+    /** Override the SES context. If omitted, createSes() is used (reads SES_FROM_EMAIL from env). */
+    ses?: SesContext;
 }
 /**
  * Hydrates a fully populated DomainContext from a Lambda invocation event and options bag.

package/dist/runtime/hydrate.js

@@ -16,6 +16,7 @@ import { extractObservabilityBindings } from './observability-bindings.js';
 import { createStore, createNoopStore } from './store.js';
 import { createFiles, createNoopFiles } from './files.js';
 import { createCognito } from './cognito.js';
+import { createSes } from './ses.js';
 /**
  * Hydrates a fully populated DomainContext from a Lambda invocation event and options bag.
  * All 14 DomainContext fields are populated. Fields with AWS dependencies fall back to
@@ -172,6 +173,7 @@ export async function hydrateCtx(_event, options = {}) {
         ? createFiles({ bucketName: options.domainBucketName ?? process.env['DOMAIN_BUCKET_NAME'], tenantId: tenant.id, tenantRoleArn: process.env['DOMAIN_TENANT_ROLE_ARN'] })
         : createNoopFiles());
     const cognito = options.cognito ?? createCognito();
+    const ses = options.ses ?? createSes();
     ctx = {
         db,
         publish,
@@ -192,6 +194,7 @@ export async function hydrateCtx(_event, options = {}) {
         store,
         files,
         cognito,
+        ses,
         pathParams: options.pathParams ?? {},
     };
     return ctx;

package/dist/runtime/index.d.ts

@@ -62,3 +62,5 @@ export { createStore, createNoopStore } from './store.js';
 export { createFiles, createNoopFiles } from './files.js';
 export { createCognito, createNoopCognito } from './cognito.js';
 export type { CognitoOptions } from './cognito.js';
+export { createSes, createNoopSes } from './ses.js';
+export type { SesOptions } from './ses.js';

package/dist/runtime/index.js

@@ -64,3 +64,4 @@ export { healthHandler, readinessHandler } from './health-handler.js';
 export { createStore, createNoopStore } from './store.js';
 export { createFiles, createNoopFiles } from './files.js';
 export { createCognito, createNoopCognito } from './cognito.js';
+export { createSes, createNoopSes } from './ses.js';

package/dist/runtime/ses.d.ts

@@ -0,0 +1,29 @@
+import type { SesContext } from '../ctx/ses.js';
+/** Options for the SES context factory. */
+export interface SesOptions {
+    /**
+     * Default from address for outgoing emails. Defaults to process.env.SES_FROM_EMAIL.
+     * If not set, the factory returns a noop context that throws on any call.
+     */
+    fromAddress?: string;
+    /**
+     * AWS region. Defaults to process.env.SES_AWS_REGION or process.env.AWS_REGION.
+     */
+    region?: string;
+}
+/**
+ * Create a SES-backed SesContext.
+ *
+ * The SDK client is created lazily on first use. The `fromAddress` is
+ * captured at construction time from `SES_FROM_EMAIL` — domain code
+ * never needs to pass it.
+ *
+ * @param options - SesOptions. If fromAddress is not resolved, returns a noop.
+ * @returns A SesContext backed by the AWS SDK, or a noop that throws.
+ */
+export declare function createSes(options?: SesOptions): SesContext;
+/**
+ * Create a noop SesContext for tests or environments without SES.
+ * Every method throws with a clear message.
+ */
+export declare function createNoopSes(): SesContext;

package/dist/runtime/ses.js

@@ -0,0 +1,58 @@
+/**
+ * Create a SES-backed SesContext.
+ *
+ * The SDK client is created lazily on first use. The `fromAddress` is
+ * captured at construction time from `SES_FROM_EMAIL` — domain code
+ * never needs to pass it.
+ *
+ * @param options - SesOptions. If fromAddress is not resolved, returns a noop.
+ * @returns A SesContext backed by the AWS SDK, or a noop that throws.
+ */
+export function createSes(options = {}) {
+    const fromAddress = options.fromAddress ?? process.env['SES_FROM_EMAIL'];
+    if (!fromAddress) {
+        return createNoopSes();
+    }
+    const region = options.region ?? process.env['SES_AWS_REGION'] ?? process.env['AWS_REGION'] ?? 'eu-north-1';
+    let client;
+    async function getClient() {
+        if (!client) {
+            const sdk = await import('@aws-sdk/client-ses');
+            client = new sdk.SESClient({ region });
+        }
+        return client;
+    }
+    return {
+        async sendEmail(params) {
+            const sdk = await import('@aws-sdk/client-ses');
+            const c = await getClient();
+            const result = await c.send(new sdk.SendEmailCommand({
+                Source: params.from ?? fromAddress,
+                Destination: {
+                    ToAddresses: Array.isArray(params.to) ? params.to : [params.to],
+                },
+                Message: {
+                    Subject: { Data: params.subject, Charset: 'UTF-8' },
+                    Body: {
+                        ...(params.htmlBody ? { Html: { Data: params.htmlBody, Charset: 'UTF-8' } } : {}),
+                        ...(params.textBody ? { Text: { Data: params.textBody, Charset: 'UTF-8' } } : {}),
+                    },
+                },
+                ...(params.replyTo ? {
+                    ReplyToAddresses: Array.isArray(params.replyTo) ? params.replyTo : [params.replyTo],
+                } : {}),
+            }));
+            return { messageId: result.MessageId };
+        },
+    };
+}
+/**
+ * Create a noop SesContext for tests or environments without SES.
+ * Every method throws with a clear message.
+ */
+export function createNoopSes() {
+    const msg = 'ctx.ses: SES_FROM_EMAIL is not set. Configure the email stack to enable SES operations.';
+    return {
+        async sendEmail() { throw new Error(msg); },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-runtime",
-  "version": "0.2.75",
+  "version": "0.2.77",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -48,6 +48,7 @@
     "@aws-sdk/client-eventbridge": "^3.0.0",
     "@aws-sdk/client-lambda": "^3.0.0",
     "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/client-ses": "^3.0.0",
     "@aws-sdk/client-secrets-manager": "^3.0.0",
     "@aws-sdk/client-sfn": "^3.0.0",
     "@aws-sdk/client-sqs": "^3.0.0",