@everystack/events 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `@everystack/events` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.4] - 2026-10-30
+
+### Added
+
+- createListener takes a role and switches to it once per session
+
+## [0.4.3] - 2026-10-23
+
+### Fixed
+
+- sign KVS purges with an explicit SigV4a signer
+- KVS client shares the signer's credentials; prove the send path signs
+- cache_purge retries ETag conflicts and fails loudly
+
 ## [0.4.2] - 2026-10-15
 
 _Internal changes only._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/events",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "PostgreSQL LISTEN/NOTIFY bridge for serverless — WebSocket fan-out + Lambda invocation",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -64,7 +64,7 @@
     }
   },
   "dependencies": {
-    "@everystack/model": "0.4.21"
+    "@everystack/model": "0.4.25"
   },
   "peerDependencies": {
     "@aws-sdk/client-apigatewaymanagementapi": "3.1053.0",
@@ -105,10 +105,11 @@
     "@types/react": "19.2.14",
     "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
+    "postgres": "3.4.9",
     "react": "19.2.0",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/auth": "0.4.9"
+    "@everystack/auth": "0.4.10"
   },
   "scripts": {
     "test": "jest",

package/src/dispatchers.ts

@@ -3,6 +3,8 @@ import type {
   RpcActionConfig, JobActionConfig, CachePurgeActionConfig,
 } from './types';
 import { resolveTemplate, filterByTenant, needsRowFetch, applyFilter } from './actions';
+import { emitKvsMetrics, MAX_LOGGED_UNPURGED_PATHS, resolveKvsMetricsOrDefault, type KvsMetricsSetting } from './kvs-metrics';
+import { backoffMs, DEFAULT_MAX_ATTEMPTS, isEtagConflict, KvsPurgeError, realSleep } from './kvs-purge';
 
 // --- Interfaces for injectable dependencies ---
 
@@ -16,12 +18,34 @@ export interface LambdaClient {
 
 export interface KvsClient {
   describe(kvsArn: string): Promise<{ ETag: string }>;
-  put(kvsArn: string, key: string, value: string, etag: string): Promise<void>;
+  /**
+   * Write one key with IfMatch. Return the store's new ETag when the answer
+   * carries it, so the next path skips a Describe; return nothing and the
+   * next path describes first.
+   */
+  put(kvsArn: string, key: string, value: string, etag: string): Promise<void | { ETag?: string }>;
+}
+
+export interface CachePurgeOptions {
+  /** Wait between conflict retries. Test-only. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Attempts per path before giving up. Default 5. */
+  maxAttempts?: number;
+  /**
+   * One EMF line per cache_purge dispatch, success and failure. `false` turns
+   * it off. A bad setting logs one error line and the defaults are used.
+   */
+  metrics?: KvsMetricsSetting;
 }
 
 export interface DispatchOptions {
   workerFunctionName?: string;
   defaultKvsArn?: string | null;
+  /** Called once per failed cache_purge. A throw or rejection is ignored. */
+  onError?: (error: KvsPurgeError) => void | Promise<void>;
+  metrics?: KvsMetricsSetting;
+  /** Wait between conflict retries. Test-only. */
+  sleep?: (ms: number) => Promise<void>;
 }
 
 // --- Individual dispatchers ---
@@ -79,7 +103,13 @@ export async function dispatchJob(
 
 /**
  * Dispatch a cache_purge action: invalidate CloudFront KVS paths.
- * Lightweight — runs directly in the listener, no Lambda invocation.
+ * Lightweight: runs directly in the listener, no Lambda invocation.
+ *
+ * Same rules as `invalidateKvsPaths` in packages/server/src/kvs.ts: paths are
+ * deduped; each put writes with IfMatch; on an ETag conflict that path
+ * re-reads the ETag and retries with a jittered backoff (5 attempts). A path
+ * that cannot be written stops the purge and throws a KvsPurgeError listing
+ * it and every later path. One EMF line per dispatch, after the retries.
  */
 export async function dispatchCachePurge(
   action: EventAction,
@@ -87,19 +117,82 @@ export async function dispatchCachePurge(
   row: Record<string, unknown> | null,
   kvsClient: KvsClient | null,
   defaultKvsArn: string | null,
+  options: CachePurgeOptions = {},
 ): Promise<void> {
   const resolved = resolveTemplate(action.config, event, row) as CachePurgeActionConfig;
   const kvsArn = resolved.kvsArn || defaultKvsArn;
-  if (!kvsArn || !kvsClient) return;
+  if (!kvsArn || !kvsClient || resolved.paths.length === 0) return;
 
-  const desc = await kvsClient.describe(kvsArn);
-  let etag = desc.ETag;
+  // mirror of packages/server/src/kvs.ts, keep in sync
+  const metrics = resolveKvsMetricsOrDefault(options.metrics);
+  const sleep = options.sleep ?? realSleep;
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const unique = [...new Set(resolved.paths)];
+  const value = String(Math.floor(Date.now() / 1000));
 
-  for (const path of resolved.paths) {
-    await kvsClient.put(kvsArn, path, String(Math.floor(Date.now() / 1000)), etag);
-    // KVS etag changes after each put — re-describe for next iteration
-    const newDesc = await kvsClient.describe(kvsArn);
-    etag = newDesc.ETag;
+  let written = 0;
+  try {
+    // The ETag moves after every put, ours or another writer's. A put that
+    // returns the new ETag saves the next Describe; anything else reads it fresh.
+    let etag: string | undefined;
+    for (; written < unique.length; written++) {
+      for (let attempt = 1; ; attempt++) {
+        if (etag === undefined) etag = (await kvsClient.describe(kvsArn)).ETag;
+        try {
+          const out = await kvsClient.put(kvsArn, unique[written], value, etag);
+          etag = out ? out.ETag : undefined;
+          break;
+        } catch (err) {
+          etag = undefined;
+          if (!isEtagConflict(err) || attempt >= maxAttempts) throw err;
+          await sleep(backoffMs(attempt));
+        }
+      }
+    }
+  } catch (err) {
+    const unpurged = unique.slice(written);
+    emitKvsMetrics(metrics, {
+      kvsArn,
+      metrics: { KvsPurgeFailure: 1, KvsPurgePaths: written, KvsPurgeUnpurgedPaths: unpurged.length },
+      unpurgedPaths: unpurged,
+    });
+    throw new KvsPurgeError(
+      `KVS purge stopped: ${written} of ${unique.length} paths written; `
+        + `${unpurged.length} ${unpurged.length === 1 ? 'path' : 'paths'} not purged`,
+      { unpurgedPaths: unpurged, writtenPaths: unique.slice(0, written), cause: err },
+    );
+  }
+
+  emitKvsMetrics(metrics, {
+    kvsArn,
+    metrics: { KvsPurgeFailure: 0, KvsPurgePaths: unique.length, KvsPurgeUnpurgedPaths: 0 },
+    unpurgedPaths: [],
+  });
+}
+
+/**
+ * A failed cache_purge must be loud and must not block the event's other
+ * actions: log one line, hand the error to onError, and never reject.
+ */
+async function reportCachePurgeFailure(
+  action: EventAction,
+  err: unknown,
+  onError: DispatchOptions['onError'],
+): Promise<void> {
+  try {
+    if (err instanceof KvsPurgeError) {
+      const shown = err.unpurgedPaths.slice(0, MAX_LOGGED_UNPURGED_PATHS);
+      const more = err.unpurgedPaths.length - shown.length;
+      console.error(
+        `cache_purge action ${action.id}: ${err.message}. Unpurged: ${shown.join(', ')}`
+          + (more > 0 ? ` (+${more} more)` : ''),
+      );
+      if (onError) await onError(err);
+    } else {
+      console.error(`cache_purge action ${action.id} failed: ${(err as Error)?.message ?? String(err)}`);
+    }
+  } catch {
+    // A broken hook or log must not turn into a rejection on the listener.
   }
 }
 
@@ -162,8 +255,10 @@ export async function dispatchActions(
         break;
       case 'cache_purge':
         tasks.push(
-          dispatchCachePurge(action, event, row, kvsClient, options.defaultKvsArn ?? null)
-            .catch(() => {})
+          dispatchCachePurge(action, event, row, kvsClient, options.defaultKvsArn ?? null, {
+            metrics: options.metrics,
+            sleep: options.sleep,
+          }).catch((err) => reportCachePurgeFailure(action, err, options.onError))
         );
         break;
       case 'webhook':

package/src/index.ts

@@ -2,6 +2,9 @@ export { createListener, createListenerInternal } from './listener';
 export { generateTriggerSQL, generateEventActionsTriggerSQL } from './triggers';
 export { matchEventActions, needsRowFetch, filterByTenant, applyFilter, resolveTemplate, createActionCache } from './actions';
 export { dispatchActions, dispatchRpc, dispatchJob, dispatchCachePurge } from './dispatchers';
+export type { KvsClient, DispatchOptions, CachePurgeOptions } from './dispatchers';
+export { KvsPurgeError } from './kvs-purge';
+export type { KvsMetricsOptions, KvsMetricsSetting } from './kvs-metrics';
 export { createConnectHandler, createDisconnectHandler, createDefaultHandler } from './handler/index';
 export { createEventsClient, EventsProvider, useEventsClient, useSignal, useSubscription } from './client/index';
 export type {

package/src/kvs-client.ts

@@ -0,0 +1,59 @@
+import type { KvsClient } from './dispatchers';
+
+/**
+ * Build a KVS client that signs with an explicit SigV4a signer.
+ *
+ * Duplicate of `createKvsClient` in packages/server/src/kvs.ts (events does not
+ * depend on @everystack/server). Keep the two in step.
+ *
+ * KVS endpoints require SigV4a. A side-effect `import('@aws-sdk/signature-v4a')`
+ * registers the signer into one copy of @smithy/signature-v4, but the KVS client
+ * can carry a nested copy whose container is empty, and every request then fails
+ * with "Neither CRT nor JS SigV4a implementation is available". When
+ * `config.signer` is set the SDK uses it directly and reads no container.
+ *
+ * The credentials provider and sha256 come from a throwaway client, so the
+ * signer uses the same default chain and hash the SDK would have used.
+ * The `as string` imports keep these optional peers out of type resolution.
+ */
+export async function createKvsSdkClient(region?: string): Promise<any> {
+  const { SignatureV4a } = await import('@aws-sdk/signature-v4a' as string);
+  const { CloudFrontKeyValueStoreClient } = await import('@aws-sdk/client-cloudfront-keyvaluestore' as string);
+
+  const { credentials, sha256 } = new CloudFrontKeyValueStoreClient({ region }).config;
+  const signer = new SignatureV4a({
+    credentials,
+    region: '*',
+    service: 'cloudfront-keyvaluestore',
+    sha256,
+  });
+  // Same provider on the kept client, so there is one credential chain, not two.
+  return new CloudFrontKeyValueStoreClient({ region, signer, credentials });
+}
+
+/**
+ * The `KvsClient` the cache_purge dispatcher uses, over a KVS SDK client.
+ * `put` returns the ETag the PutKey answer carries, so the next path in the
+ * same purge skips its Describe.
+ */
+export async function kvsDispatchClient(client: any): Promise<KvsClient> {
+  const {
+    DescribeKeyValueStoreCommand,
+    PutKeyCommand,
+  } = await import('@aws-sdk/client-cloudfront-keyvaluestore' as string);
+  return {
+    describe: async (kvsArn: string) => {
+      const desc = await client.send(new DescribeKeyValueStoreCommand({ KvsARN: kvsArn }));
+      return { ETag: desc.ETag! };
+    },
+    put: async (kvsArn: string, key: string, value: string, etag: string) => {
+      const out = await client.send(new PutKeyCommand({
+        KvsARN: kvsArn,
+        Key: key,
+        Value: value,
+        IfMatch: etag,
+      }));
+      return { ETag: out?.ETag };
+    },
+  };
+}

package/src/kvs-metrics.ts

@@ -0,0 +1,154 @@
+/**
+ * CloudWatch embedded metric format (EMF) lines for the cache_purge path.
+ *
+ * Mirror of packages/server/src/kvs-metrics.ts, keep in sync. events does not
+ * depend on @everystack/server, so the same line shape is copied here with
+ * `source: 'events'` and without the check metric (events has no check).
+ *
+ * A line written to stdout in Lambda becomes a CloudWatch metric with no SDK
+ * call and no extra IAM. It is written with `process.stdout.write`, never a
+ * `console` method: under the Lambda JSON log format, Lambda wraps console
+ * output in its own JSON event and CloudWatch does not extract metrics from
+ * the wrapped object.
+ */
+
+export const DEFAULT_KVS_METRICS_NAMESPACE = 'Everystack/Cache';
+export const MAX_KVS_METRIC_DIMENSIONS = 2;
+/** The unpurgedPaths property keeps this many entries; the metric keeps the full count. */
+export const MAX_LOGGED_UNPURGED_PATHS = 20;
+
+export type KvsMetricName = 'KvsPurgeFailure' | 'KvsPurgePaths' | 'KvsPurgeUnpurgedPaths';
+
+export interface KvsMetricsOptions {
+  /** CloudWatch namespace. Default `Everystack/Cache`. */
+  namespace?: string;
+  /**
+   * Replaces the default dimension (`FunctionName` from
+   * AWS_LAMBDA_FUNCTION_NAME). At most 2 keys; `{}` means no dimension.
+   */
+  dimensions?: Record<string, string>;
+  /** Written as a property so one request can be found in Logs Insights. */
+  requestId?: string;
+}
+
+/** `false` turns emission off. */
+export type KvsMetricsSetting = false | KvsMetricsOptions;
+
+export interface ResolvedKvsMetrics {
+  namespace: string;
+  dimensions: Record<string, string>;
+  requestId?: string;
+}
+
+export interface KvsMetricPoint {
+  kvsArn: string;
+  metrics: Partial<Record<KvsMetricName, number>>;
+  unpurgedPaths?: string[];
+}
+
+// mirror of packages/server/src/kvs-metrics.ts, keep in sync
+const PROPERTY_NAMES = ['_aws', 'kvsArn', 'source', 'unpurgedPaths', 'requestId'];
+const METRIC_NAMES: KvsMetricName[] = ['KvsPurgeFailure', 'KvsPurgePaths', 'KvsPurgeUnpurgedPaths'];
+// The server's check metric stays reserved so one setting is valid in both packages.
+const RESERVED = new Set<string>([...PROPERTY_NAMES, ...METRIC_NAMES, 'KvsPurgeCheckFailure']);
+
+// mirror of packages/server/src/kvs-metrics.ts, keep in sync
+/**
+ * Resolve the namespace and dimensions once, at call time. Returns null when
+ * metrics are off. Throws on more than 2 dimensions or a reserved dimension
+ * name; the purge catches that through resolveKvsMetricsOrDefault.
+ */
+export function resolveKvsMetrics(
+  setting?: KvsMetricsSetting,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedKvsMetrics | null {
+  if (setting === false) return null;
+  const options = setting ?? {};
+
+  let dimensions: Record<string, string>;
+  if (options.dimensions) {
+    const names = Object.keys(options.dimensions);
+    if (names.length > MAX_KVS_METRIC_DIMENSIONS) {
+      throw new Error(
+        `KVS metrics: at most ${MAX_KVS_METRIC_DIMENSIONS} dimensions, got ${names.length} `
+          + `(${names.join(', ')}). Put high-cardinality values in properties, not dimensions.`,
+      );
+    }
+    const reserved = names.filter((n) => RESERVED.has(n));
+    if (reserved.length > 0) {
+      throw new Error(
+        `KVS metrics: dimension name ${reserved.join(', ')} is reserved for a property or metric.`,
+      );
+    }
+    dimensions = { ...options.dimensions };
+  } else {
+    const fn = env.AWS_LAMBDA_FUNCTION_NAME;
+    dimensions = fn ? { FunctionName: fn } : {};
+  }
+
+  return {
+    namespace: options.namespace ?? DEFAULT_KVS_METRICS_NAMESPACE,
+    dimensions,
+    ...(options.requestId ? { requestId: options.requestId } : {}),
+  };
+}
+
+// mirror of packages/server/src/kvs-metrics.ts, keep in sync
+/**
+ * Resolve the setting for a purge. A bad setting must never stop a purge
+ * (stale beats down): log one error line naming the problem and fall back to
+ * the default metrics.
+ */
+export function resolveKvsMetricsOrDefault(
+  setting?: KvsMetricsSetting,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedKvsMetrics | null {
+  try {
+    return resolveKvsMetrics(setting, env);
+  } catch (err) {
+    console.error(`KVS metrics setting ignored, using the defaults: ${(err as Error).message}`);
+    return resolveKvsMetrics(undefined, env);
+  }
+}
+
+// mirror of packages/server/src/kvs-metrics.ts, keep in sync
+/** Build one EMF object. Dimensions and metrics are top-level members. */
+export function buildKvsEmf(
+  resolved: ResolvedKvsMetrics,
+  point: KvsMetricPoint,
+  now: number = Date.now(),
+): Record<string, unknown> {
+  const names = METRIC_NAMES.filter((n) => point.metrics[n] !== undefined);
+  return {
+    _aws: {
+      Timestamp: now,
+      CloudWatchMetrics: [{
+        Namespace: resolved.namespace,
+        Dimensions: [Object.keys(resolved.dimensions)],
+        Metrics: names.map((Name) => ({ Name, Unit: 'Count' })),
+      }],
+    },
+    ...resolved.dimensions,
+    ...Object.fromEntries(names.map((n) => [n, point.metrics[n]])),
+    kvsArn: point.kvsArn,
+    source: 'events',
+    ...(point.unpurgedPaths
+      ? { unpurgedPaths: point.unpurgedPaths.slice(0, MAX_LOGGED_UNPURGED_PATHS) }
+      : {}),
+    ...(resolved.requestId ? { requestId: resolved.requestId } : {}),
+  };
+}
+
+// mirror of packages/server/src/kvs-metrics.ts, keep in sync
+/**
+ * Write one EMF line to stdout. Never throws: a metric that cannot be written
+ * must not turn a purge, or a purge failure, into a different error.
+ */
+export function emitKvsMetrics(resolved: ResolvedKvsMetrics | null, point: KvsMetricPoint): void {
+  if (!resolved) return;
+  try {
+    process.stdout.write(JSON.stringify(buildKvsEmf(resolved, point)) + '\n');
+  } catch {
+    // Nothing to do: the metric is lost, the caller's outcome is not.
+  }
+}

package/src/kvs-purge.ts

@@ -0,0 +1,52 @@
+/**
+ * The retry rules and the error type of a KVS purge.
+ *
+ * events does not depend on @everystack/server, so these are copied from
+ * packages/server/src/kvs.ts. The error has the same name and shape there and
+ * here, so one consumer guard (`err.name === 'KvsPurgeError'`) covers both.
+ */
+
+// mirror of packages/server/src/kvs.ts, keep in sync
+export const DEFAULT_MAX_ATTEMPTS = 5;
+const BACKOFF_BASE_MS = 25;
+const BACKOFF_CAP_MS = 400;
+
+// mirror of packages/server/src/kvs.ts, keep in sync
+/** A purge that stopped part way. `unpurgedPaths` are the keys NOT written. */
+export class KvsPurgeError extends Error {
+  readonly unpurgedPaths: string[];
+  readonly writtenPaths: string[];
+
+  constructor(
+    message: string,
+    details: { unpurgedPaths: string[]; writtenPaths: string[]; cause: unknown },
+  ) {
+    super(message, { cause: details.cause });
+    this.name = 'KvsPurgeError';
+    this.unpurgedPaths = details.unpurgedPaths;
+    this.writtenPaths = details.writtenPaths;
+  }
+}
+
+// mirror of packages/server/src/kvs.ts, keep in sync
+/**
+ * A write refused because another writer moved the ETag first. The KVS API
+ * models this as ConflictException (409); 412 PreconditionFailed is matched
+ * too in case the service ever answers with the HTTP precondition status.
+ */
+export function isEtagConflict(err: unknown): boolean {
+  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } } | null;
+  const status = e?.$metadata?.httpStatusCode;
+  return status === 409 || status === 412
+    || e?.name === 'ConflictException'
+    || e?.name === 'PreconditionFailed'
+    || e?.name === 'PreconditionFailedException';
+}
+
+// mirror of packages/server/src/kvs.ts, keep in sync
+export function backoffMs(attempt: number): number {
+  const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));
+  return ceiling / 2 + Math.random() * (ceiling / 2);
+}
+
+export const realSleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));

package/src/listener.ts

@@ -2,6 +2,7 @@ import type { EventPayload, EventAction, EventActionsOptions, ListenerOptions, L
 import { matchEventActions, createActionCache } from './actions';
 import { dispatchActions } from './dispatchers';
 import type { KvsClient } from './dispatchers';
+import { createKvsSdkClient, kvsDispatchClient } from './kvs-client';
 
 // --- Subscription state (in-memory) ---
 
@@ -275,6 +276,26 @@ async function reconcile(
   await loadEventActions(pgClient, actionCache);
 }
 
+// --- Session role ---
+
+const ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+
+/** The role is spliced into SET ROLE, so it must be a plain identifier; never the lifecycle role. */
+function assertListenerRole(role: string): void {
+  if (!ROLE_NAME.test(role)) throw new Error(`Invalid role name: ${JSON.stringify(role)}`);
+  if (role === 'everystack_lifecycle') throw new Error('the listener must not run as everystack_lifecycle: pass an application role (e.g. admin)');
+}
+
+/**
+ * Switch the session to `role` and prove it took. Session-level, not SET LOCAL: LISTEN is
+ * session-scoped and the listener holds one session for its whole run, outside any transaction.
+ */
+async function switchSessionRole(pgClient: InternalListenerOptions['pgClient'], role: string): Promise<void> {
+  await pgClient.query(`SET ROLE ${role}`);
+  const { rows } = await pgClient.query('SELECT current_user AS role');
+  if (rows[0]?.role !== role) throw new Error(`role ${role} was not set: current_user is ${String(rows[0]?.role)}`);
+}
+
 // --- Internal (testable) listener factory ---
 
 interface InternalListenerOptions {
@@ -293,6 +314,8 @@ interface InternalListenerOptions {
   heartbeatInterval?: number;
   eventActions?: EventActionsOptions;
   kvsClient?: KvsClient | null;
+  /** See ListenerOptions.role. */
+  role?: string;
 }
 
 interface HandlerEvent {
@@ -310,11 +333,22 @@ export function createListenerInternal(options: InternalListenerOptions) {
     heartbeatInterval = 30000,
     eventActions,
     kvsClient = null,
+    role,
   } = options;
+  if (role !== undefined) assertListenerRole(role);
 
   return async function handler(event: HandlerEvent = {}): Promise<{ status: string; reason?: string }> {
-    // 1. Connect
+    // 1. Connect, then switch role before anything else runs in this session. This is the only
+    // connect: the session is never re-opened, so the switch covers everything after it.
     await pgClient.connect();
+    if (role !== undefined) {
+      try {
+        await switchSessionRole(pgClient, role);
+      } catch (err) {
+        await pgClient.end().catch(() => {});
+        throw err;
+      }
+    }
 
     // 2. Acquire advisory lock
     const { rows } = await pgClient.query(
@@ -358,6 +392,8 @@ export function createListenerInternal(options: InternalListenerOptions) {
             dispatchActions(matched, ev, pgClient, lambdaClient, kvsClient, {
               workerFunctionName: eventActions?.workerFunctionName,
               defaultKvsArn: eventActions?.defaultKvsArn,
+              onError: eventActions?.onError,
+              metrics: eventActions?.metrics,
             });
           }
         }
@@ -390,6 +426,7 @@ export function createListenerInternal(options: InternalListenerOptions) {
 // --- Public API ---
 
 export function createListener(options: ListenerOptions) {
+  if (options.role !== undefined) assertListenerRole(options.role);
   return async function handler(_event?: unknown): Promise<{ status: string; reason?: string }> {
     // Dynamic imports to avoid bundling AWS SDK when not needed
     const { default: pg } = await import('pg' as string);
@@ -430,27 +467,7 @@ export function createListener(options: ListenerOptions) {
     let kvsClient: KvsClient | null = null;
     if (options.eventActions?.defaultKvsArn) {
       try {
-        await import('@aws-sdk/signature-v4a' as string);
-        const {
-          CloudFrontKeyValueStoreClient,
-          DescribeKeyValueStoreCommand,
-          PutKeyCommand,
-        } = await import('@aws-sdk/client-cloudfront-keyvaluestore' as string);
-        const client = new CloudFrontKeyValueStoreClient({});
-        kvsClient = {
-          describe: async (kvsArn: string) => {
-            const desc = await client.send(new DescribeKeyValueStoreCommand({ KvsARN: kvsArn }));
-            return { ETag: desc.ETag! };
-          },
-          put: async (kvsArn: string, key: string, value: string, etag: string) => {
-            await client.send(new PutKeyCommand({
-              KvsARN: kvsArn,
-              Key: key,
-              Value: value,
-              IfMatch: etag,
-            }));
-          },
-        };
+        kvsClient = await kvsDispatchClient(await createKvsSdkClient());
       } catch {
         // KVS SDK not available — skip cache_purge actions
       }
@@ -466,6 +483,7 @@ export function createListener(options: ListenerOptions) {
       heartbeatInterval: options.heartbeatInterval,
       eventActions: options.eventActions,
       kvsClient,
+      role: options.role,
     });
 
     return internal({});

package/src/types.ts

@@ -1,3 +1,6 @@
+import type { KvsMetricsSetting } from './kvs-metrics';
+import type { KvsPurgeError } from './kvs-purge';
+
 // --- Core ---
 
 export interface EventPayload {
@@ -33,6 +36,10 @@ export interface ListenerRoutes {
 export interface EventActionsOptions {
   workerFunctionName?: string;
   defaultKvsArn?: string | null;
+  /** Called once per failed cache_purge. A throw or rejection is ignored. */
+  onError?: (error: KvsPurgeError) => void | Promise<void>;
+  /** One EMF line per cache_purge dispatch (`source: 'events'`). `false` turns it off. */
+  metrics?: KvsMetricsSetting;
 }
 
 export interface ListenerOptions {
@@ -43,6 +50,12 @@ export interface ListenerOptions {
   reconcile?: (db: unknown) => Promise<void>;
   heartbeatInterval?: number;
   eventActions?: EventActionsOptions;
+  /**
+   * An application role to `SET ROLE` to right after connect, checked with `current_user`.
+   * Lets the listener connect as a least-privilege login (NOINHERIT, granted the role) instead
+   * of the owner. Each invocation opens a new session and switches it. Omit to stay as the login.
+   */
+  role?: string;
 }
 
 // --- Subscription (internal NOTIFY payloads) ---