@antelopejs/dms-mailing 0.9.0 → 0.9.1

package/frontend-vue/package.json

@@ -1,38 +1,39 @@
 {
-	"name": "@antelopejs/dms-mailing-frontend-vue",
-	"version": "0.0.1",
-	"private": true,
-	"type": "module",
-	"license": "Apache-2.0",
-	"packageManager": "pnpm@10.2.0",
-	"engines": {
-		"@antelopejs/dms-frontend": ">=0.10.0 <0.11.0"
-	},
-	"scripts": {
-		"format": "prettier --write .",
-		"lint": "eslint . && node --input-type=module -e \"import { assertApiErrorPresentation } from '@antelopejs/dms/checks/api-error-presentation'; assertApiErrorPresentation(['app']);\"",
-		"lint:fix": "eslint . --fix",
-		"test": "vitest run"
-	},
-	"dependencies": {
-		"@vueuse/core": "^14.3.0",
-		"@vueuse/integrations": "^14.3.0",
-		"sortablejs": "^1.14.0",
-		"vue": "^3.5.18"
-	},
-	"devDependencies": {
-		"@antelopejs/tooling-configs": "^0.2.12",
-		"@nuxt/ui": "4.10.0",
-		"@vitejs/plugin-vue": "^6.0.0",
-		"@vitest/runner": "^4.1.5",
-		"eslint": "^9.0.0",
-		"eslint-plugin-vue": "^10.0.0",
-		"typescript-eslint": "^8.0.0",
-		"vite": "^8.2.2",
-		"jsdom": "^26",
-		"prettier": "^3.5.3",
-		"prettier-plugin-tailwindcss": "^0.6.11",
-		"typescript": "^5.9.3",
-		"vitest": "^4.1.5"
-	}
+  "name": "@antelopejs/dms-mailing-frontend-vue",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "license": "Apache-2.0",
+  "packageManager": "pnpm@10.2.0",
+  "engines": {
+    "@antelopejs/dms-frontend": ">=0.10.0 <0.11.0"
+  },
+  "scripts": {
+    "format": "prettier --write .",
+    "lint": "eslint . && node --input-type=module -e \"import { assertApiErrorPresentation } from '@antelopejs/dms/checks/api-error-presentation'; assertApiErrorPresentation(['app']);\"",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@vueuse/core": "^14.3.0",
+    "@vueuse/integrations": "^14.3.0",
+    "sortablejs": "^1.14.0",
+    "vue": "^3.5.18"
+  },
+  "devDependencies": {
+    "@antelopejs/tooling-configs": "^0.3.3",
+    "@nuxt/ui": "4.10.0",
+    "@types/sortablejs": "^1.15.9",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "@vitest/runner": "^4.1.5",
+    "eslint": "^9.0.0",
+    "eslint-plugin-vue": "^10.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vite": "^8.2.2",
+    "jsdom": "^26",
+    "prettier": "^3.5.3",
+    "prettier-plugin-tailwindcss": "^0.6.11",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  }
 }

package/frontend-vue/pnpm-lock.yaml

@@ -22,11 +22,14 @@ importers:
         version: 3.5.42(typescript@5.9.3)
     devDependencies:
       '@antelopejs/tooling-configs':
-        specifier: ^0.2.12
-        version: 0.2.17
+        specifier: ^0.3.3
+        version: 0.3.3
       '@nuxt/ui':
         specifier: 4.10.0
         version: 4.10.0(9bdbb06d8a0b4accef61070adc217622)
+      '@types/sortablejs':
+        specifier: ^1.15.9
+        version: 1.15.9
       '@vitejs/plugin-vue':
         specifier: ^6.0.0
         version: 6.0.9(vite@8.2.2(esbuild@0.28.2)(jiti@2.7.0)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.42(typescript@5.9.3))
@@ -67,16 +70,20 @@ packages:
     resolution: {integrity: sha512-U4+70Pc5ZS9osnCBCE5Jha/ciHM+Yp+CNMNC/7HvYbNRk1Ldd+f7qO65W5qfhu/TCv+/ozljlXXe9Nj8419DMA==}
     engines: {node: '>=10'}
 
-  '@antelopejs/tooling-configs@0.2.17':
-    resolution: {integrity: sha512-8fwh7xQPzazP/l/ivEwRKpfN8qShV9+PRizpI9cBewe2TwoRPu4n95w6sYSlygiRmm0HxLJYZFhmSPRgtiNo1Q==}
+  '@antelopejs/tooling-configs@0.3.3':
+    resolution: {integrity: sha512-jQ09zavCF5MMQtfyd8YOqpoxV6l6bp3m9tA5iN0z0XhQpVHM5VWr53yEuQ6Mc+1tseBW85N94ruP4TEfiGg8iQ==}
     engines: {node: '>=22.18.0'}
     hasBin: true
     peerDependencies:
       '@nuxt/eslint-config': '>=1.2.0'
       eslint-plugin-perfectionist: '>=5.0.0'
       knip: '>=6.0.0'
+      mongodb-memory-server: '>=10.0.0'
       oxfmt: ^0.66.0
       oxlint: 1.81.0
+      pixelmatch: '>=7.0.0'
+      playwright-core: '>=1.56.0'
+      sharp: '>=0.34.0'
     peerDependenciesMeta:
       '@nuxt/eslint-config':
         optional: true
@@ -84,10 +91,18 @@ packages:
         optional: true
       knip:
         optional: true
+      mongodb-memory-server:
+        optional: true
       oxfmt:
         optional: true
       oxlint:
         optional: true
+      pixelmatch:
+        optional: true
+      playwright-core:
+        optional: true
+      sharp:
+        optional: true
 
   '@antfu/install-pkg@2.0.1':
     resolution: {integrity: sha512-iCKVQcIC0e3oDxEfs3SHQGW+ovhBMZmS1TE+bTk50rVyMCBmCfClv7Qi3HQKlumYwvjb/iIMeWCW2i67q6kFfQ==}
@@ -1413,6 +1428,9 @@ packages:
   '@types/json-schema@7.0.15':
     resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
 
+  '@types/sortablejs@1.15.9':
+    resolution: {integrity: sha512-7HP+rZGE2p886PKV9c9OJzLBI6BBJu1O7lJGYnPyG3fS4/duUCcngkNCjsLwIMV+WMqANe3tt4irrXHSIe68OQ==}
+
   '@types/web-bluetooth@0.0.20':
     resolution: {integrity: sha512-g9gZnnXVq7gM7v3tJCWV/qw7w+KeOlSHAhgF9RytFyifW6AF61hdT2ucrYhPq9hLs5JIryeupHV3qGk95dH9ow==}
 
@@ -3372,7 +3390,7 @@ snapshots:
 
   '@alloc/quick-lru@5.3.0': {}
 
-  '@antelopejs/tooling-configs@0.2.17':
+  '@antelopejs/tooling-configs@0.3.3':
     dependencies:
       '@oxlint/plugins': 1.81.0
       dts-bundle-generator: 9.5.1
@@ -4552,6 +4570,8 @@ snapshots:
 
   '@types/json-schema@7.0.15': {}
 
+  '@types/sortablejs@1.15.9': {}
+
   '@types/web-bluetooth@0.0.20': {}
 
   '@types/web-bluetooth@0.0.21': {}

package/frontend-vue/tests/editor-canvas.test.ts

@@ -0,0 +1,142 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h } from 'vue'
+import EditorCanvas from '../app/components/editor/EditorCanvas.vue'
+import { useEditorActions } from '../app/composables/useEditorActions'
+import { provideEditorContext } from '../app/composables/useEditorContext'
+import { useEditorSession } from '../app/composables/useEditorSession'
+import { useMailingApi } from '../app/composables/useMailingApi'
+import { useEditorReads } from '../app/composables/useMailingReads'
+import { createEditorState } from '../app/composables/useTemplateEditor'
+import type {
+	TemplateContent,
+	TemplateContentResponse,
+} from '../app/types/mailing'
+import { stubApiData } from './helpers/api-data'
+import { stubAuthFetch } from './helpers/auth-fetch'
+import { mount, slotStub, stubNuxtGlobals } from './helpers/nuxt-globals'
+import type { Mounted } from './helpers/nuxt-globals'
+
+const CLIENT_BASE_URL = 'https://dms.acme.com'
+const DEFAULT_SVG = '/logo.svg'
+const DEFAULT_PNG = 'https://cdn.acme.com/logo.png'
+const EMAIL_PNG = 'https://cdn.acme.com/email-logo.png'
+const DARK_PNG = 'https://cdn.acme.com/email-logo-dark.png'
+
+const CONTENT: TemplateContent = {
+	locales: { en: { subject: 'Hi', preheader: '', blocks: [] } },
+}
+
+const LOADED: TemplateContentResponse = {
+	template: {
+		_id: 't1',
+		slug: 'welcome',
+		name: 'Welcome',
+		status: 'draft',
+		updatedAt: '2026-10-01T10:00:00Z',
+		updatedBy: 'camille',
+		attention: '',
+	},
+	content: CONTENT,
+	publishedContent: null,
+	hasDraft: true,
+	version: 0,
+	revision: 1,
+	changes: [],
+	variables: [],
+	detectedVariables: [],
+	testData: {},
+	fallbackLocale: 'en',
+	blockOnMissingVariables: false,
+	categories: [],
+	sender: { name: '', email: '', replyTo: '' },
+}
+
+interface LogoBranding {
+	default?: { light?: string }
+	email?: { light?: string; dark?: string }
+}
+
+/** The canvas inside an editor built as the workspace builds it. */
+const CanvasInEditor = defineComponent({
+	setup() {
+		const editor = createEditorState(CONTENT, 'en', ['en'])
+		const api = useMailingApi()
+		const reads = useEditorReads('t1')
+		const deps = { editor, api, reads, templateId: 't1', onError: () => {} }
+		const session = useEditorSession({ ...deps, loaded: LOADED })
+		const actions = useEditorActions({
+			...deps,
+			session,
+			reload: async () => {},
+		})
+		provideEditorContext({ editor, session, actions, api, templateId: 't1' })
+		return () => h(EditorCanvas)
+	},
+})
+
+let mounted: Mounted | null = null
+
+/** The logo the canvas header shows under `logo`, or null when it shows none. */
+function canvasLogo(logo: LogoBranding): string | null {
+	vi.stubGlobal('useDmsAppConfig', () => ({ branding: { logo } }))
+	mounted = mount(
+		CanvasInEditor,
+		{},
+		{
+			UAlert: slotStub('UAlert'),
+			MailingEditorEnvelope: slotStub('MailingEditorEnvelope'),
+			MailingEditorMissingLocale: slotStub('MailingEditorMissingLocale'),
+			MailingEditorBlockList: slotStub('MailingEditorBlockList'),
+		},
+	)
+	return mounted.host.querySelector('img')?.getAttribute('src') ?? null
+}
+
+beforeEach(() => {
+	stubNuxtGlobals()
+	stubApiData()
+	stubAuthFetch()
+	vi.stubGlobal('useDmsRuntimeConfig', () => ({
+		public: { dms: { clientBaseUrl: CLIENT_BASE_URL } },
+	}))
+})
+
+afterEach(() => {
+	mounted?.unmount()
+	mounted = null
+	vi.unstubAllGlobals()
+})
+
+describe('editor canvas logo header', () => {
+	it('shows the e-mail logo over an SVG default logo, as the sent e-mail does', () => {
+		expect(
+			canvasLogo({
+				default: { light: DEFAULT_SVG },
+				email: { light: EMAIL_PNG },
+			}),
+		).toBe(EMAIL_PNG)
+	})
+	it('prefers the light e-mail logo over a public default logo and the dark one', () => {
+		expect(
+			canvasLogo({
+				default: { light: DEFAULT_PNG },
+				email: { light: EMAIL_PNG, dark: DARK_PNG },
+			}),
+		).toBe(EMAIL_PNG)
+	})
+	it('falls back to the default logo when no e-mail logo is set', () => {
+		expect(canvasLogo({ default: { light: DEFAULT_PNG } })).toBe(DEFAULT_PNG)
+	})
+	it('shows no logo when the chosen one is an SVG a mail client refuses', () => {
+		expect(canvasLogo({ default: { light: DEFAULT_SVG } })).toBeNull()
+	})
+	it('does not fall back to the default logo when the e-mail logo is refused', () => {
+		expect(
+			canvasLogo({
+				default: { light: DEFAULT_PNG },
+				email: { light: DEFAULT_SVG },
+			}),
+		).toBeNull()
+	})
+})

package/frontend-vue/tests/sortable-list.test-d.ts

@@ -0,0 +1,19 @@
+/**
+ * `ajs dms verify-source` type-checks the layer against the installed
+ * `@vueuse/integrations`: the composable has to compile against its
+ * `useSortable` overloads, which take the list as a `MaybeRef`, not a getter.
+ */
+import type { Ref } from 'vue'
+import { describe, expectTypeOf, it } from 'vitest'
+import { useSortableList } from '../app/composables/useSortableList'
+
+describe('useSortableList', () => {
+	it('takes the list as a getter and compiles against useSortable', () => {
+		expectTypeOf(useSortableList<{ id: string }>)
+			.parameter(1)
+			.toEqualTypeOf<() => { id: string }[]>()
+		expectTypeOf(useSortableList<{ id: string }>)
+			.parameter(0)
+			.toEqualTypeOf<Ref<HTMLElement | null>>()
+	})
+})

package/frontend-vue/tsconfig.typecheck.json

@@ -0,0 +1,12 @@
+{
+	"compilerOptions": {
+		"target": "esnext",
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"lib": ["esnext", "dom"],
+		"strict": true,
+		"noEmit": true,
+		"skipLibCheck": true
+	},
+	"include": ["tests/**/*.test-d.ts"]
+}

package/frontend-vue/vitest.config.ts

@@ -1,13 +1,29 @@
+import { fileURLToPath } from 'node:url'
 import vue from '@vitejs/plugin-vue'
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
 	plugins: [vue()],
+	resolve: {
+		alias: {
+			'#dms-layout': fileURLToPath(
+				new URL(
+					'../node_modules/@antelopejs/dms/frontend-vue/layers/dms-layout',
+					import.meta.url,
+				),
+			),
+		},
+	},
 	test: {
 		// Most suites need no DOM, and setting jsdom up per file is the bulk of
 		// the run; the files that mount components opt in with a
 		// `// @vitest-environment jsdom` header.
 		environment: 'node',
 		include: ['tests/**/*.test.ts'],
+		typecheck: {
+			enabled: true,
+			include: ['tests/**/*.test-d.ts'],
+			tsconfig: 'tsconfig.typecheck.json',
+		},
 	},
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-mailing",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "E-mail templates for the AntelopeJS DMS: a block editor with drafts and versions, a send log, delivery metrics and a suppression list.",
   "keywords": [
     "antelopejs",
@@ -59,10 +59,10 @@
     "zod": "~3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.20.0",
-    "@antelopejs/dms": ">=0.16.1 <1.0.0",
+    "@antelopejs/core": "^1.21.0",
+    "@antelopejs/dms": ">=0.19.0 <1.0.0",
     "@antelopejs/mongodb": "^1.6.2",
-    "@antelopejs/tooling-configs": "^0.2.18",
+    "@antelopejs/tooling-configs": "^0.3.3",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10",
     "@types/node": "^24.0.0",

package/skills/dms-mailing/SKILL.md

@@ -83,6 +83,8 @@ export async function declareMailingContent(tenantId: string) {
   i18n keys; each user reads, searches and sorts them in their language (`x-content-language`).
 - `DeclareSender({ tenantId, email, name?, replyTo? })` writes the settings' sender (resolves `void`); call it once
   from `Hook.TENANT_BEING_PROVISIONED`, not on every boot, since it replaces what a user set. Refusals use `invalid_sender`.
+- `DeclareWebhookSecret({ tenantId, secret, replaceRotated? })` resolves `{ outcome: "set" | "unchanged" | "kept" }`, never
+  the secret; idempotent, and keeps a secret the owner set or rotated unless `replaceRotated`. Refusals use `invalid_webhook_secret`.
 - Refusals reject with `error.code`: `invalid_template`, `unknown_category`, `empty_subject`,
   `nothing_to_publish`, `invalid_category`; invalid tenant input rejects before writes. Storage errors can occur after publication.
 - `ImportSends({ tenantId, sends: [{ importId, templateSlug, to, sentAt, events }] })` writes past sends with their own

package/src/db/tables/settings.table.ts

@@ -46,4 +46,8 @@ export class MailingSettings extends Table {
 
   @Field("string")
   declare webhookSecret: string;
+
+  /** Who set `webhookSecret`; absent on rows written before it was kept. */
+  @Field("string")
+  declare webhookSecretSource?: string;
 }

package/src/hooks/tenant-export.ts

@@ -18,7 +18,10 @@ import {
 import { findSettings } from "../services/settings";
 import type { MailingSettingsValues } from "../types";
 
-export type ExportedSettings = Omit<MailingSettingsValues, "webhookSecret">;
+export type ExportedSettings = Omit<
+  MailingSettingsValues,
+  "webhookSecret" | "webhookSecretSource"
+>;
 
 export type ExportPageLoader<T> = (
   offset: number,

package/src/implementations/dms-mailing/index.ts

@@ -4,5 +4,6 @@ export {
 } from "../../services/declarations";
 export { importSends as ImportSends } from "../../services/send-import";
 export { declareSender as DeclareSender } from "../../services/sender-declaration";
+export { declareWebhookSecret as DeclareWebhookSecret } from "../../services/webhook-secret-declaration";
 export { recordEmailEvent as RecordEmailEvent } from "../../services/events";
 export { sendUnlessSuppressed as SendTemplate } from "../../services/checked-send";

package/src/pages/sends.ts

@@ -225,8 +225,9 @@ export class SendsPageController extends PageController(
     pageSize: 50,
     rowClick: "single",
     /**
-     * New sends wait in a "N new sends" strip while the user reads a send,
-     * scrolls down the log or searches it, so the rows do not move under them.
+     * New sends wait behind a "N new sends" pill while the log is on screen,
+     * so the rows do not move under the user. A send open in the drawer, a
+     * scroll down the log or a search also names the hold above the rows.
      */
     liveHold: {
       whileRowOpen: true,

package/src/routes/settings.ts

@@ -33,6 +33,7 @@ import {
   mergeSettingsPatch,
   missingVariablesPolicy,
   saveSettings,
+  saveWebhookSecret,
   WEBHOOK_SECRET_BYTES,
 } from "../services/settings";
 import {
@@ -78,7 +79,15 @@ const retentionDaysSchema = z.coerce
  * The DMS form reads and writes localized values whole
  * (`x-content-language: *`): category labels travel with every language.
  */
-export interface MailingSettingsResponse extends MailingSettingsValues {
+/** The settings as the form reads and writes them: who set the secret stays inside the module. */
+type FormSettings = Omit<MailingSettingsValues, "webhookSecretSource">;
+
+function formSettings(values: MailingSettingsValues): FormSettings {
+  const { webhookSecretSource: _source, ...form } = values;
+  return form;
+}
+
+export interface MailingSettingsResponse extends FormSettings {
   /** Where the provider posts its events; read-only. */
   webhookUrl: string;
   /** The configured provider, as the read-only provider row shows it. */
@@ -94,7 +103,7 @@ export interface SettingsNotice {
   params?: Record<string, number | string>;
 }
 
-export interface SettingsWriteResponse extends MailingSettingsValues {
+export interface SettingsWriteResponse extends FormSettings {
   notice?: SettingsNotice;
 }
 
@@ -211,7 +220,7 @@ export class MailingSettingsController extends Controller(
       readCapabilities(),
     ]);
     return {
-      ...values,
+      ...formSettings(values),
       webhookUrl: await this.providerWebhookUrl(capabilities?.name),
       provider: capabilities?.name ?? "",
       missingVariables: missingVariablesPolicy(values),
@@ -234,7 +243,7 @@ export class MailingSettingsController extends Controller(
       ? await this.reassignCategories(categories, categoryMoves(entries))
       : 0;
     const [notice] = [...reassignedNotice(reassigned), ...senderNotice(saved)];
-    return { ...saved, ...(notice && { notice }) };
+    return { ...formSettings(saved), ...(notice && { notice }) };
   }
 
   /** The body as a checked patch; 400 for anything else. */
@@ -249,12 +258,15 @@ export class MailingSettingsController extends Controller(
     );
   }
 
-  /** Issues a new webhook secret; the old one stops working at once. */
+  /**
+   * Issues a new webhook secret, the workspace owner's from now on; the old
+   * one stops working at once.
+   */
   @Post("/webhook-secret/rotate")
   async rotateSecret(): Promise<{ value: string }> {
-    const current = await getSettings(this.tenantId);
+    await getSettings(this.tenantId);
     const value = randomBytes(WEBHOOK_SECRET_BYTES).toString("hex");
-    await saveSettings(this.tenantId, { ...current, webhookSecret: value });
+    await saveWebhookSecret(this.tenantId, value, "operator");
     return { value };
   }
 

package/src/services/send-import.ts

@@ -172,10 +172,12 @@ interface EntryOutcome {
 }
 
 /**
- * Writes one send: its events first, under ids derived from the send's, then
- * the send itself. A run stopped half-way leaves events no send shows yet,
- * which the next run completes; each write skips the row an earlier run
- * wrote, and a send present means it was fully imported.
+ * Writes one send: the send itself first, then its events under ids derived
+ * from the send's. An event is written only after its send, so the
+ * retention's orphan-event pass never finds an import's events before their
+ * send. A run stopped half-way leaves a send with part of its history, which
+ * the next run completes: each write skips the row an earlier run wrote, and
+ * the events are written whether or not the send was already there.
  */
 async function importOne(
   tenantId: string,
@@ -184,8 +186,10 @@ async function importOne(
   fallbackLocale: string,
 ): Promise<EntryOutcome> {
   const id = importedSendIdOf(tenantId, send.importId);
-  const sends = GetModel(SendModel, tenantId);
   const timeline = timelineOf(send);
+  const locale = send.locale ?? fallbackLocale;
+  const row = sendRow(id, send, template, locale, foldEvents(send, timeline));
+  const isImported = await GetModel(SendModel, tenantId).insertImported(row);
   const events = GetModel(SendEventModel, tenantId);
   for (const [index, entry] of timeline.entries()) {
     await events.insertImported({
@@ -196,9 +200,7 @@ async function importOne(
       json_details: JSON.stringify(entry.details ?? {}),
     });
   }
-  const locale = send.locale ?? fallbackLocale;
-  const row = sendRow(id, send, template, locale, foldEvents(send, timeline));
-  return { id, isImported: await sends.insertImported(row) };
+  return { id, isImported };
 }
 
 /**

package/src/services/settings.ts

@@ -5,12 +5,17 @@ import {
   MODULE_DEFAULT_SETTINGS,
   type MailingSettingsValues,
   type TemplateCategory,
+  WEBHOOK_SECRET_SOURCES,
+  type WebhookSecretSource,
 } from "../types";
 import type { JsonObject } from "../types/json";
 import type { SettingsPatch } from "../validation/settings.schema";
 
 export const WEBHOOK_SECRET_BYTES = 24;
 
+const GENERATED_SECRET: WebhookSecretSource = "generated";
+const OPERATOR_SECRET: WebhookSecretSource = "operator";
+
 function defaults(): MailingSettingsValues {
   return {
     ...MODULE_DEFAULT_SETTINGS,
@@ -18,9 +23,21 @@ function defaults(): MailingSettingsValues {
     senderEmail: "",
     replyTo: "",
     webhookSecret: randomBytes(WEBHOOK_SECRET_BYTES).toString("hex"),
+    webhookSecretSource: GENERATED_SECRET,
   };
 }
 
+/**
+ * The stored source, or `operator` for a row written before the source was
+ * kept: a secret of unknown origin is the workspace's until proven otherwise.
+ */
+function storedSecretSource(stored: string | undefined): WebhookSecretSource {
+  return (
+    WEBHOOK_SECRET_SOURCES.find((source) => source === stored) ??
+    OPERATOR_SECRET
+  );
+}
+
 function toValues(row: MailingSettings): MailingSettingsValues {
   return {
     fallbackLocale: row.fallbackLocale,
@@ -30,6 +47,7 @@ function toValues(row: MailingSettings): MailingSettingsValues {
     senderEmail: row.senderEmail,
     replyTo: row.replyTo,
     webhookSecret: row.webhookSecret,
+    webhookSecretSource: storedSecretSource(row.webhookSecretSource),
     // SAFETY: json_categories is written only by toRow as the JSON.stringify of categories that categoriesSchema
     // validated (settingsPatchSchema, applyCategory) or that the module defaults supplied.
     categories: JSON.parse(row.json_categories) as TemplateCategory[],
@@ -94,6 +112,22 @@ export async function saveSettings(
   return values;
 }
 
+/**
+ * Writes the webhook secret and its source alone, so a concurrent writer of
+ * the other settings keeps its fields. The tenant's row must exist: read it
+ * with `getSettings` first.
+ */
+export async function saveWebhookSecret(
+  tenantId: string,
+  webhookSecret: string,
+  webhookSecretSource: WebhookSecretSource,
+): Promise<void> {
+  await GetModel(SettingsModel, tenantId).update(tenantId, {
+    webhookSecret,
+    webhookSecretSource,
+  });
+}
+
 export function findCategory(
   categories: TemplateCategory[],
   id: string,
@@ -125,7 +159,8 @@ export function clearedToEmpty(patch: JsonObject): JsonObject {
 /**
  * The settings once `patch` (the fields a form changed, cleared ones already
  * stored as empty) is laid over the stored ones, the missing-variables choice
- * folded back into its boolean.
+ * folded back into its boolean. A secret the patch changes becomes the
+ * workspace owner's.
  */
 export function mergeSettingsPatch(
   current: MailingSettingsValues,
@@ -137,5 +172,8 @@ export function mergeSettingsPatch(
     isChoice && !("blockOnMissingVariables" in patch)
       ? { blockOnMissingVariables: policy === REFUSE_POLICY }
       : {};
-  return { ...current, ...written, ...guard };
+  const merged = { ...current, ...written, ...guard };
+  return merged.webhookSecret === current.webhookSecret
+    ? merged
+    : { ...merged, webhookSecretSource: OPERATOR_SECRET };
 }