@antelopejs/dms-mailing 0.8.0 → 0.9.1

package/src/services/webhook-secret-declaration.ts

@@ -0,0 +1,47 @@
+import type {
+  DeclareWebhookSecretResult,
+  WebhookSecretDeclaration,
+  WebhookSecretOutcome,
+} from "@antelopejs/interface-dms-mailing";
+import type { MailingSettingsValues } from "../types";
+import { webhookSecretDeclarationSchema } from "../validation/declarations.schema";
+import { parseDeclared } from "./declaration-error";
+import { webhookSecretMatches } from "./events";
+import { getSettings, saveWebhookSecret } from "./settings";
+
+const SET: WebhookSecretOutcome = "set";
+
+/**
+ * What declaring `secret` does to the stored one: nothing when it is already
+ * stored, nothing when the workspace owner set or rotated it and the caller
+ * did not ask to replace it, else a write.
+ */
+export function webhookSecretOutcome(
+  stored: Pick<MailingSettingsValues, "webhookSecret" | "webhookSecretSource">,
+  secret: string,
+  replaceRotated: boolean,
+): WebhookSecretOutcome {
+  if (webhookSecretMatches(secret, stored.webhookSecret)) return "unchanged";
+  if (stored.webhookSecretSource === "operator" && !replaceRotated)
+    return "kept";
+  return SET;
+}
+
+/**
+ * Sets the workspace's webhook secret a project ships as code. The secret is
+ * never returned, and a refusal names the rule it broke, never the value.
+ */
+export async function declareWebhookSecret(
+  input: WebhookSecretDeclaration,
+): Promise<DeclareWebhookSecretResult> {
+  const { tenantId, secret, replaceRotated } = parseDeclared(
+    webhookSecretDeclarationSchema,
+    input,
+    "invalid_webhook_secret",
+    "webhook secret declaration",
+  );
+  const stored = await getSettings(tenantId);
+  const outcome = webhookSecretOutcome(stored, secret, replaceRotated);
+  if (outcome === SET) await saveWebhookSecret(tenantId, secret, "declared");
+  return { outcome };
+}

package/src/services/webhook-status.ts

@@ -7,6 +7,7 @@ import type {
   WebhookRefusal,
   WebhookStatus,
 } from "../types";
+import { isObject, isText } from "../validation/guards";
 import { webhookSecretMatches } from "./events";
 import { WEBHOOK_SECRET_HEADER } from "../constants";
 
@@ -28,11 +29,11 @@ export const WEBHOOK_REFUSAL_MESSAGES: Record<WebhookRefusal, string> = {
 };
 
 /** The body of a refused webhook call. */
-export interface WebhookRefusalBody {
+export type WebhookRefusalBody = {
   error: "webhook_refused";
   reason: WebhookRefusal;
   message: string;
-}
+};
 
 /** What "Send a test event" found when it called the webhook URL. */
 export interface WebhookTestOutcome {
@@ -143,17 +144,19 @@ export async function readWebhookStatus(
   );
 }
 
-const describeError = (error: unknown): string =>
-  error instanceof Error
-    ? String((error.cause as Error | undefined)?.message ?? error.message)
-    : String(error);
+function isWebhookRefusal(value: unknown): value is WebhookRefusal {
+  return isText(value) && Object.hasOwn(WEBHOOK_REFUSAL_MESSAGES, value);
+}
 
+/** The webhook's own refusal reason in a response, not one another endpoint gives. */
 async function refusalOf(
   response: Response,
 ): Promise<WebhookRefusal | undefined> {
   try {
-    const body = (await response.json()) as Partial<WebhookRefusalBody>;
-    return body.reason;
+    const body: unknown = await response.json();
+    return isObject(body) && isWebhookRefusal(body.reason)
+      ? body.reason
+      : undefined;
   } catch {
     return undefined;
   }
@@ -192,11 +195,17 @@ export async function sendWebhookTest(
       refusal: response.ok ? undefined : await refusalOf(response),
     };
   } catch (error) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    const causeMessage =
+      isObject(cause) && isText(cause.message) ? cause.message : undefined;
     return {
       isReceived: false,
       url,
       durationMs: elapsed(),
-      networkError: describeError(error),
+      networkError:
+        error instanceof Error
+          ? (causeMessage ?? error.message)
+          : String(error),
     };
   }
 }

package/src/types/json.ts

@@ -0,0 +1 @@
+export type { JsonObject, JsonValue } from "@antelopejs/interface-dms-mailing";

package/src/types/settings.ts

@@ -1,11 +1,11 @@
 import type { LocalizedText } from "@antelopejs/interface-dms-mailing";
 
 /** A template category as stored: its label written once per language. */
-export interface TemplateCategory {
+export type TemplateCategory = {
   id: string;
   label: LocalizedText;
   icon: string;
-}
+};
 
 /** A template category as one reader sees it: the label in their language. */
 export interface CategoryInLocale {
@@ -14,6 +14,19 @@ export interface CategoryInLocale {
   icon: string;
 }
 
+/**
+ * Who set the webhook secret: the module drew it (`generated`), a project
+ * declared it (`declared`), or the workspace owner set or rotated it in the
+ * settings (`operator`). A declaration replaces only the first two.
+ */
+export const WEBHOOK_SECRET_SOURCES = [
+  "generated",
+  "declared",
+  "operator",
+] as const;
+
+export type WebhookSecretSource = (typeof WEBHOOK_SECRET_SOURCES)[number];
+
 export interface MailingSettingsValues {
   fallbackLocale: string;
   logRetentionDays: number;
@@ -22,6 +35,7 @@ export interface MailingSettingsValues {
   senderEmail: string;
   replyTo: string;
   webhookSecret: string;
+  webhookSecretSource: WebhookSecretSource;
   categories: TemplateCategory[];
 }
 

package/src/validation/declarations.schema.ts

@@ -8,6 +8,7 @@ import {
   templateContentSchema,
   variableListSchema,
 } from "./templates.schema";
+import { jsonObjectSchema } from "./json.schema";
 
 const MAX_AUTHOR_LENGTH = MAX_NAME_LENGTH;
 const MAX_IMPORT_ID_LENGTH = 200;
@@ -36,7 +37,7 @@ export const templateDeclarationSchema = z.object({
   category: z.string().trim().default(""),
   content: templateContentSchema,
   variables: variableListSchema.default([]),
-  testData: z.record(z.unknown()).default({}),
+  testData: jsonObjectSchema.default({}),
   author: z.string().trim().min(1).max(MAX_AUTHOR_LENGTH).optional(),
 });
 
@@ -67,6 +68,13 @@ export const senderDeclarationSchema = z.object({
 
 export type ParsedSenderDeclaration = z.infer<typeof senderDeclarationSchema>;
 
+/** A webhook secret declared from code: the settings form's rule. */
+export const webhookSecretDeclarationSchema = z.object({
+  tenantId: tenantIdSchema,
+  secret: settingsSchema.shape.webhookSecret,
+  replaceRotated: z.boolean().default(false),
+});
+
 const recipientSchema = z.union([
   z.string().trim().email(),
   z.object({
@@ -78,7 +86,7 @@ const recipientSchema = z.union([
 const importedEventSchema = z.object({
   type: sendEventTypeSchema,
   at: z.coerce.date(),
-  details: z.record(z.unknown()).optional(),
+  details: jsonObjectSchema.optional(),
 });
 
 const importedSendSchema = z.object({
@@ -87,7 +95,7 @@ const importedSendSchema = z.object({
   to: recipientSchema,
   sentAt: z.coerce.date(),
   locale: z.string().trim().min(1).optional(),
-  variables: z.record(z.unknown()).default({}),
+  variables: jsonObjectSchema.default({}),
   provider: z.string().optional(),
   providerMessageId: z.string().optional(),
   source: z.string().optional(),

package/src/validation/guards.ts

@@ -3,14 +3,6 @@ export function isText(value: unknown): value is string {
   return typeof value === "string";
 }
 
-/**
- * Whether `value` is a JSON object as a parsed body holds one: an object,
- * neither `null` nor an array. Its values are not checked.
- */
-export function isJsonObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Whether `value` is an object, arrays included, and not `null`: reading any
  * key of it yields a value of unknown type.

package/src/validation/json.schema.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { isJsonObject } from "./json";
+
+/** A JSON object whose every value is JSON data, such as a request body carries. */
+export const jsonObjectSchema = z
+  .unknown()
+  .refine(isJsonObject, "expected a JSON object");

package/src/validation/json.ts

@@ -0,0 +1,66 @@
+import type { JsonObject, JsonValue } from "../types/json";
+import { isNumber, isObject, isText } from "./guards";
+
+/** A step of the walk in {@link isJsonValue}: visit a node, or leave one. */
+type JsonWalkStep = { visit: unknown } | { leave: object };
+
+/**
+ * Whether `value` is wholly JSON data: strings, numbers, booleans, null, and
+ * arrays and plain objects of the same, none of them reached through itself.
+ * Walked with a stack, so a deeply nested value cannot overflow it.
+ */
+export function isJsonValue(value: unknown): value is JsonValue {
+  const stack: JsonWalkStep[] = [{ visit: value }];
+  const ancestors = new Set<object>();
+  for (let step = stack.pop(); step; step = stack.pop()) {
+    if ("leave" in step) {
+      ancestors.delete(step.leave);
+      continue;
+    }
+    const item = step.visit;
+    if (
+      item === null ||
+      isText(item) ||
+      isNumber(item) ||
+      typeof item === "boolean"
+    )
+      continue;
+    if (typeof item !== "object" || ancestors.has(item)) return false;
+    const prototype: unknown = Object.getPrototypeOf(item);
+    if (
+      !Array.isArray(item) &&
+      prototype !== Object.prototype &&
+      prototype !== null
+    )
+      return false;
+    ancestors.add(item);
+    stack.push({ leave: item });
+    for (const child of Object.values(item)) stack.push({ visit: child });
+  }
+  return true;
+}
+
+/** Whether `value` is wholly JSON data and an object: neither `null` nor an array. */
+export function isJsonObject(value: unknown): value is JsonObject {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    isJsonValue(value)
+  );
+}
+
+/** `text` parsed as JSON; a `SyntaxError` when it is not. */
+export function parseJson(text: string): JsonValue {
+  const parsed: unknown = JSON.parse(text);
+  if (!isJsonValue(parsed)) throw new TypeError("expected JSON data");
+  return parsed;
+}
+
+/** `text` parsed as a JSON object. */
+export function parseJsonObject(text: string): JsonObject {
+  const parsed = parseJson(text);
+  if (!isObject(parsed) || Array.isArray(parsed))
+    throw new TypeError("expected a JSON object");
+  return parsed;
+}

package/src/validation/templates.schema.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { MAX_NAME_LENGTH, MAX_SLUG_LENGTH, SLUG_PATTERN } from "../constants";
 import type { Block } from "../types";
+import { jsonObjectSchema } from "./json.schema";
 
 const MIN_HEADING_SIZE = 12;
 const MAX_HEADING_SIZE = 48;
@@ -149,7 +150,7 @@ export const saveContentSchema = z.object({
   revision: draftRevisionSchema,
 });
 
-export const testDataSchema = z.object({ data: z.record(z.unknown()) });
+export const testDataSchema = z.object({ data: jsonObjectSchema });
 
 /**
  * Which content a preview renders when it carries none: the working draft
@@ -166,7 +167,7 @@ export const previewSchema = z.object({
   locale: z.string().min(1).optional(),
   version: previewVersionSchema.optional(),
   content: templateContentSchema.optional(),
-  data: z.record(z.unknown()).optional(),
+  data: jsonObjectSchema.optional(),
 });
 
 /**
@@ -176,7 +177,7 @@ export const previewSchema = z.object({
 export const realSendSchema = z.object({
   to: z.array(z.string().email()).min(1).max(MAX_TEST_RECIPIENT_COUNT),
   locale: z.string().min(1).optional(),
-  data: z.record(z.unknown()).optional(),
+  data: jsonObjectSchema.optional(),
 });
 
 export const testSendSchema = previewSchema.extend({
@@ -193,6 +194,9 @@ export const templateDetailsSchema = z.object({
   category: z.string().nullable().optional(),
 });
 
+/** The details a template's drawer or the editor saves, validated. */
+export type TemplateDetails = z.infer<typeof templateDetailsSchema>;
+
 export const duplicateSchema = z.object({
   slug: slugSchema,
   name: z.string().trim().min(1).max(MAX_NAME_LENGTH),