@cosmicdrift/kumiko-samples 0.377.0 → 0.379.0

package/packages/bundled-features/src/template-resolver/handlers/resource-upload.write.ts

@@ -15,7 +15,6 @@ import {
   readFileRefContent,
 } from "../../file-foundation/index.ts";
 import { attachmentFileNameSchema } from "../../shared/index.ts";
-import { TemplateResolverErrors } from "../qualified-names.ts";
 import {
   type PreparedTemplateFile,
   prepareTemplateAttachmentBeforeTransaction,
@@ -26,6 +25,12 @@ import {
   storePreparedTemplateAttachment,
   storePreparedTemplateResource,
 } from "../store-template-resource.ts";
+import {
+  refuseTemplateEditById,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
+import { TemplateResolverErrors } from "../web/qualified-names.ts";
 import { RESOURCE_PURPOSES, resourceKeySchema, resourceTargetTenantId } from "./resource-shared.ts";
 
 type AttachmentTarget = {
@@ -48,127 +53,142 @@ function attachmentTargetOf(input: {
 // Purpose "image": stores a re-encoded image as a FileRef and, with templateId + key, links it into
 // the template; without templateId it only creates the FileRef (the branding logo upload path).
 // Purpose "attachment": stores the file as uploaded and links it as a mail attachment.
-export const resourceUploadWrite = defineWriteHandler({
-  name: "resource-upload",
-  schema: z
-    .object({
-      templateId: z.string().min(1).optional(),
-      key: resourceKeySchema.optional(),
-      /** An unclaimed upload of the caller (POST /api/files without entityType). */
-      sourceFileRefId: z.uuid(),
-      /** Cross-tenant target — SystemAdmin only. */
-      tenantIdOverride: z.string().min(1).optional(),
-      /** "attachment" links a PDF/PNG/JPEG as a file attached to every mail of the template. */
-      purpose: z.enum(RESOURCE_PURPOSES).default("image"),
-      /** Name the recipient sees; required for purpose "attachment". */
-      fileName: z.string().optional(),
-    })
-    .refine(
-      (p) => p.purpose === "attachment" || (p.templateId === undefined) === (p.key === undefined),
-      {
-        message: "templateId and key must be given together",
-        path: ["key"],
-      },
-    ),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Turns a file uploaded via POST /api/files (multipart, no entityType) into a template resource. With purpose image (default) the upload is checked against the resource-max-bytes cap, re-encoded to a supported image format and stored as a new file; with templateId and key it is linked into that template under the key, without them only the file is created. With purpose attachment, templateId, key and fileName are required: a PDF, PNG or JPEG is stored unchanged and linked into a mail template as a file attached to every mail sent from it, at most 10 per template. A cap above the files route's maxUploadSize has no effect.",
-  beforeTransaction: async (event, ctx): Promise<BeforeTransactionResult<PreparedTemplateFile>> => {
-    const { templateId, key, sourceFileRefId, purpose, fileName } = event.payload;
-    const attachmentTarget =
-      purpose === "attachment" ? attachmentTargetOf({ templateId, key, fileName }) : null;
-    if (purpose === "attachment" && attachmentTarget === null) {
-      return writeFailure(
-        new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
-          i18nKey: "templateResolver.errors.attachment.invalid",
-          details: { code: "target_required" },
-        }),
-      );
-    }
-    const maxBytes = await readTemplateResourceMaxBytes(ctx.config, ctx.registry);
-
-    // The source is read from the session tenant only: with tenantIdOverride the upload
-    // sits in the admin's own tenant while the normalized file lands in the target tenant.
-    // Only the caller's own unclaimed upload qualifies, so a record-attached image of
-    // someone else cannot be copied into a template.
-    let source: Awaited<ReturnType<typeof readFileRefContent>>;
-    try {
-      source = await readFileRefContent({
-        db: ctx.db,
-        filesForTenant: (tid) => fileContextForTenant(ctx, ctx.user.tenantId, tid),
-        fileRefId: sourceFileRefId,
-        allowedTenantIds: [event.user.tenantId],
-        unclaimedUploadOf: event.user.id,
-        maxBytes,
-      });
-    } catch (cause) {
-      if (cause instanceof FileRefTooLargeError) {
+export function makeResourceUploadWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "resource-upload",
+    schema: z
+      .object({
+        templateId: z.string().min(1).optional(),
+        key: resourceKeySchema.optional(),
+        /** An unclaimed upload of the caller (POST /api/files without entityType). */
+        sourceFileRefId: z.uuid(),
+        /** Cross-tenant target — SystemAdmin only. */
+        tenantIdOverride: z.string().min(1).optional(),
+        /** "attachment" links a PDF/PNG/JPEG as a file attached to every mail of the template. */
+        purpose: z.enum(RESOURCE_PURPOSES).default("image"),
+        /** Name the recipient sees; required for purpose "attachment". */
+        fileName: z.string().optional(),
+      })
+      .refine(
+        (p) => p.purpose === "attachment" || (p.templateId === undefined) === (p.key === undefined),
+        {
+          message: "templateId and key must be given together",
+          path: ["key"],
+        },
+      ),
+    access: templateEditAccess(policy.tenantEditable),
+    description:
+      "Turns a file uploaded via POST /api/files (multipart, no entityType) into a template resource. With purpose image (default) the upload is checked against the resource-max-bytes cap, re-encoded to a supported image format and stored as a new file; with templateId and key it is linked into that template under the key, without them only the file is created. With purpose attachment, templateId, key and fileName are required: a PDF, PNG or JPEG is stored unchanged and linked into a mail template as a file attached to every mail sent from it, at most 10 per template. A cap above the files route's maxUploadSize has no effect. Only a SystemAdmin and the roles of the templates the app lists in tenantEditable may use it; such a role may link only into those templates.",
+    beforeTransaction: async (
+      event,
+      ctx,
+    ): Promise<BeforeTransactionResult<PreparedTemplateFile>> => {
+      const { templateId, key, sourceFileRefId, purpose, fileName } = event.payload;
+      const attachmentTarget =
+        purpose === "attachment" ? attachmentTargetOf({ templateId, key, fileName }) : null;
+      if (purpose === "attachment" && attachmentTarget === null) {
         return writeFailure(
-          new UnprocessableError(TemplateResolverErrors.resourceTooLarge, {
-            i18nKey: "templateResolver.errors.resource.tooLarge",
-            details: { maxBytes, size: cause.size },
+          new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+            i18nKey: "templateResolver.errors.attachment.invalid",
+            details: { code: "target_required" },
           }),
         );
       }
-      throw cause;
-    }
-    if (source === null) return writeFailure(new NotFoundError("file-ref", sourceFileRefId));
+      if (templateId !== undefined) {
+        const refused = await refuseTemplateEditById(
+          ctx.db,
+          policy,
+          event.user,
+          resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId),
+          templateId,
+        );
+        if (refused !== null) return refused;
+      }
+      const maxBytes = await readTemplateResourceMaxBytes(ctx.config, ctx.registry);
 
-    // The source upload stays as an unclaimed file: bundled-features cannot reach the fileRef executor to delete it.
-    const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
-    if (attachmentTarget !== null) {
-      return prepareTemplateAttachmentBeforeTransaction({
+      // The source is read from the session tenant only: with tenantIdOverride the upload
+      // sits in the admin's own tenant while the normalized file lands in the target tenant.
+      // Only the caller's own unclaimed upload qualifies, so a record-attached image of
+      // someone else cannot be copied into a template.
+      let source: Awaited<ReturnType<typeof readFileRefContent>>;
+      try {
+        source = await readFileRefContent({
+          db: ctx.db,
+          filesForTenant: (tid) => fileContextForTenant(ctx, ctx.user.tenantId, tid),
+          fileRefId: sourceFileRefId,
+          allowedTenantIds: [event.user.tenantId],
+          unclaimedUploadOf: event.user.id,
+          maxBytes,
+        });
+      } catch (cause) {
+        if (cause instanceof FileRefTooLargeError) {
+          return writeFailure(
+            new UnprocessableError(TemplateResolverErrors.resourceTooLarge, {
+              i18nKey: "templateResolver.errors.resource.tooLarge",
+              details: { maxBytes, size: cause.size },
+            }),
+          );
+        }
+        throw cause;
+      }
+      if (source === null) return writeFailure(new NotFoundError("file-ref", sourceFileRefId));
+
+      // The source upload stays as an unclaimed file: bundled-features cannot reach the fileRef executor to delete it.
+      const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
+      if (attachmentTarget !== null) {
+        return prepareTemplateAttachmentBeforeTransaction({
+          ctx,
+          user: event.user,
+          tenantId,
+          bytes: source.content,
+          maxBytes,
+          ...attachmentTarget,
+        });
+      }
+      return prepareTemplateResourceBeforeTransaction({
         ctx,
         user: event.user,
         tenantId,
         bytes: source.content,
         maxBytes,
-        ...attachmentTarget,
+        ...(templateId !== undefined && { templateId }),
+        ...(key !== undefined && { key }),
       });
-    }
-    return prepareTemplateResourceBeforeTransaction({
+    },
+    handler: async (
+      event,
       ctx,
-      user: event.user,
-      tenantId,
-      bytes: source.content,
-      maxBytes,
-      ...(templateId !== undefined && { templateId }),
-      ...(key !== undefined && { key }),
-    });
-  },
-  handler: async (
-    event,
-    ctx,
-  ): Promise<WriteResult<StoredTemplateResource | StoredTemplateAttachment>> => {
-    const { templateId, key } = event.payload;
-    const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
-    const { prepared } = event;
-    if (prepared.kind === "attachment") {
-      // The phase accepts attachments only with a complete target, so these are set.
-      if (templateId === undefined || key === undefined) {
-        return writeFailure(
-          new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
-            i18nKey: "templateResolver.errors.attachment.invalid",
-            details: { code: "target_required" },
-          }),
-        );
+    ): Promise<WriteResult<StoredTemplateResource | StoredTemplateAttachment>> => {
+      const { templateId, key } = event.payload;
+      const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
+      const { prepared } = event;
+      if (prepared.kind === "attachment") {
+        // The phase accepts attachments only with a complete target, so these are set.
+        if (templateId === undefined || key === undefined) {
+          return writeFailure(
+            new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+              i18nKey: "templateResolver.errors.attachment.invalid",
+              details: { code: "target_required" },
+            }),
+          );
+        }
+        return storePreparedTemplateAttachment({
+          ctx,
+          user: event.user,
+          tenantId,
+          prepared,
+          templateId,
+          key,
+        });
       }
-      return storePreparedTemplateAttachment({
+      return storePreparedTemplateResource({
         ctx,
         user: event.user,
         tenantId,
         prepared,
-        templateId,
-        key,
+        ...(templateId !== undefined && { templateId }),
+        ...(key !== undefined && { key }),
       });
-    }
-    return storePreparedTemplateResource({
-      ctx,
-      user: event.user,
-      tenantId,
-      prepared,
-      ...(templateId !== undefined && { templateId }),
-      ...(key !== undefined && { key }),
-    });
-  },
-});
+    },
+  });
+}

package/packages/bundled-features/src/template-resolver/handlers/send-test-shared.ts

@@ -0,0 +1,38 @@
+import type { HandlerContext, Registry, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type ChannelContext,
+  collectChannels,
+  createEmailAttachmentReader,
+  EMAIL_CHANNEL_NAME,
+} from "../../delivery/index.ts";
+import { fileContextForTenant } from "../../file-foundation/index.ts";
+
+export function emailChannelOf(registry: Registry) {
+  return collectChannels(registry).find((channel) => channel.name === EMAIL_CHANNEL_NAME);
+}
+
+export function testMailChannelContext(ctx: HandlerContext, user: SessionUser): ChannelContext {
+  return {
+    db: ctx.db,
+    registry: ctx.registry,
+    sseBroker: undefined,
+    tenantId: user.tenantId,
+    secrets: ctx.secrets,
+    config: ctx.config,
+    readAttachment: createEmailAttachmentReader(
+      ctx.db,
+      ctx.registry,
+      user.tenantId,
+      ctx.config,
+      (tenantId) => fileContextForTenant(ctx, ctx.user.tenantId, tenantId),
+    ),
+  };
+}
+
+export async function resolveTestMailAddress(
+  channel: NonNullable<ReturnType<typeof emailChannelOf>>,
+  channelContext: ChannelContext,
+  user: SessionUser,
+): Promise<string | null> {
+  return (await channel.resolve?.(user.id, channelContext)) ?? null;
+}

package/packages/bundled-features/src/template-resolver/handlers/send-test-status.query.ts

@@ -0,0 +1,31 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import {
+  emailChannelOf,
+  resolveTestMailAddress,
+  testMailChannelContext,
+} from "./send-test-shared.ts";
+
+export type SendTestStatus =
+  | { readonly canSend: true; readonly reason: null }
+  | { readonly canSend: false; readonly reason: "no_channel" | "no_address" };
+
+export const sendTestStatusQuery = defineQueryHandler({
+  name: "send-test-status",
+  schema: z.object({}),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Tells whether send-test can reach the calling user: canSend is true when an email channel is mounted and resolves an address for the caller, otherwise reason is no_channel or no_address; the address itself is never returned.",
+  handler: async (query, ctx): Promise<SendTestStatus> => {
+    const channel = emailChannelOf(ctx.registry);
+    if (channel === undefined) return { canSend: false, reason: "no_channel" };
+    const address = await resolveTestMailAddress(
+      channel,
+      testMailChannelContext(ctx, query.user),
+      query.user,
+    );
+    return address === null
+      ? { canSend: false, reason: "no_address" }
+      : { canSend: true, reason: null };
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/send-test.write.ts

@@ -1,23 +1,23 @@
-import { defineWriteHandler, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import {
-  collectChannels,
-  createEmailAttachmentReader,
-  EMAIL_CHANNEL_NAME,
-} from "../../delivery/index.ts";
-import { fileContextForTenant } from "../../file-foundation/index.ts";
-import { TEST_MAIL_SUBJECT_PREFIX } from "../constants.ts";
-import { TemplateResolverErrors } from "../qualified-names.ts";
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { renderTemplatePreview } from "../template-preview.ts";
+import { TEST_MAIL_SUBJECT_PREFIX } from "../web/constants.ts";
+import { TemplateResolverErrors } from "../web/qualified-names.ts";
+import {
+  emailChannelOf,
+  resolveTestMailAddress,
+  testMailChannelContext,
+} from "./send-test-shared.ts";
 import { localeSchema, templateSlugSchema } from "./shared.ts";
 
 const TEST_MAIL_RATE_LIMIT = { limit: 10, windowSeconds: 3600 } as const;
 
-function emailChannelOf(registry: Registry) {
-  return collectChannels(registry).find((channel) => channel.name === EMAIL_CHANNEL_NAME);
-}
-
 // Transport errors can carry provider responses or the address, so the client only gets a fixed code.
 function testMailFailed(code: "channel_error" | "not_sent") {
   return writeFailure(
@@ -34,105 +34,99 @@ function errorCodeOf(error: unknown): string | undefined {
 }
 
 // The only recipient is the caller's own address, resolved server-side, so the handler can never mail a third party.
-export const sendTestWrite = defineWriteHandler({
-  name: "send-test",
-  schema: z.object({
-    slug: templateSlugSchema,
-    locale: localeSchema,
-    content: z.string().max(200_000).optional(),
-    meta: z.unknown().optional(),
-    variableSchema: z.record(z.string(), z.unknown()).default({}),
-    variables: z.record(z.string(), z.unknown()).optional(),
-    includeAttachments: z.boolean().default(true),
-    prefixSubject: z.boolean().default(true),
-  }),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  rateLimit: { per: "user+handler", ...TEST_MAIL_RATE_LIMIT },
-  description:
-    "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples unless variables replaces them (checked against the variable schema), and a draft that fails the write rules is rejected without sending.",
-  handler: async (event, ctx) => {
-    const { includeAttachments, prefixSubject, ...previewPayload } = event.payload;
-    const outcome = await renderTemplatePreview(ctx, event.user, {
-      ...previewPayload,
-      kind: "mail",
-    });
-    if (!outcome.ok) return writeFailure(outcome.error);
-    const { preview, sender } = outcome;
-    const mailAttachments = includeAttachments
-      ? outcome.mailAttachments
-      : outcome.mailAttachments.filter((ref) => ref.kind === "inline");
-
-    const channel = emailChannelOf(ctx.registry);
-    if (channel === undefined) {
-      return writeFailure(
-        new UnprocessableError(TemplateResolverErrors.testMailNoChannel, {
-          i18nKey: "templateResolver.errors.testMail.noChannel",
-        }),
-      );
-    }
-    const channelContext = {
-      db: ctx.db,
-      registry: ctx.registry,
-      sseBroker: undefined,
-      tenantId: event.user.tenantId,
-      secrets: ctx.secrets,
-      config: ctx.config,
-      readAttachment: createEmailAttachmentReader(
-        ctx.db,
-        ctx.registry,
-        event.user.tenantId,
-        ctx.config,
-        (tenantId) => fileContextForTenant(ctx, ctx.user.tenantId, tenantId),
-      ),
-    };
-    const address = (await channel.resolve?.(event.user.id, channelContext)) ?? null;
-    if (address === null) {
-      return writeFailure(
-        new UnprocessableError(TemplateResolverErrors.testMailNoAddress, {
-          i18nKey: "templateResolver.errors.testMail.noAddress",
-        }),
-      );
-    }
-
-    const subject = `${prefixSubject ? TEST_MAIL_SUBJECT_PREFIX : ""}${preview.subject ?? ""}`;
-    let sentStatus: string;
-    try {
-      const result = await channel.send(
-        address,
-        {
-          // The template slug is the notification name, so the test mail takes the transport the real mail takes.
-          notificationType: event.payload.slug,
-          title: subject,
-          body: undefined,
-          data: undefined,
-          locale: event.payload.locale,
-        },
-        channelContext,
-        {
-          subject,
-          html: preview.html,
-          text: preview.text ?? "",
-          ...sender,
-          attachments: mailAttachments,
-        },
-      );
-      sentStatus = result.status;
-    } catch (error) {
-      // Class and code only: the message can carry the address or a provider response body.
-      ctx.log?.warn("template test mail: channel threw", {
-        tenantId: event.user.tenantId,
-        errorClass: error instanceof Error ? error.name : typeof error,
-        errorCode: errorCodeOf(error),
+export function makeSendTestWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "send-test",
+    schema: z.object({
+      slug: templateSlugSchema,
+      locale: localeSchema,
+      content: z.string().max(200_000).optional(),
+      meta: z.unknown().optional(),
+      variableSchema: z.record(z.string(), z.unknown()).default({}),
+      variables: z.record(z.string(), z.unknown()).optional(),
+      includeAttachments: z.boolean().default(true),
+      prefixSubject: z.boolean().default(true),
+    }),
+    access: templateEditAccess(policy.tenantEditable),
+    rateLimit: { per: "user+handler", ...TEST_MAIL_RATE_LIMIT },
+    description:
+      "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples unless variables replaces them (checked against the variable schema), and a draft that fails the write rules is rejected without sending.",
+    handler: async (event, ctx) => {
+      // Sending a test is part of editing, so it follows the same edit policy as the editor writes.
+      const refused = refuseTemplateEdit(policy, event.user, {
+        slug: event.payload.slug,
+        kind: "mail",
       });
-      return testMailFailed("channel_error");
-    }
-    if (sentStatus !== "sent") {
-      ctx.log?.warn("template test mail: channel did not send", {
-        tenantId: event.user.tenantId,
-        status: sentStatus,
+      if (refused !== null) return refused;
+      const { includeAttachments, prefixSubject, ...previewPayload } = event.payload;
+      const outcome = await renderTemplatePreview(ctx, event.user, {
+        ...previewPayload,
+        kind: "mail",
       });
-      return testMailFailed("not_sent");
-    }
-    return { isSuccess: true as const, data: { subject, checks: preview.checks } };
-  },
-});
+      if (!outcome.ok) return writeFailure(outcome.error);
+      const { preview, sender } = outcome;
+      const mailAttachments = includeAttachments
+        ? outcome.mailAttachments
+        : outcome.mailAttachments.filter((ref) => ref.kind === "inline");
+
+      const channel = emailChannelOf(ctx.registry);
+      if (channel === undefined) {
+        return writeFailure(
+          new UnprocessableError(TemplateResolverErrors.testMailNoChannel, {
+            i18nKey: "templateResolver.errors.testMail.noChannel",
+          }),
+        );
+      }
+      const channelContext = testMailChannelContext(ctx, event.user);
+      const address = await resolveTestMailAddress(channel, channelContext, event.user);
+      if (address === null) {
+        return writeFailure(
+          new UnprocessableError(TemplateResolverErrors.testMailNoAddress, {
+            i18nKey: "templateResolver.errors.testMail.noAddress",
+          }),
+        );
+      }
+
+      const subject = `${prefixSubject ? TEST_MAIL_SUBJECT_PREFIX : ""}${preview.subject ?? ""}`;
+      let sentStatus: string;
+      try {
+        const result = await channel.send(
+          address,
+          {
+            // The template slug is the notification name, so the test mail takes the transport the real mail takes.
+            notificationType: event.payload.slug,
+            title: subject,
+            body: undefined,
+            data: undefined,
+            locale: event.payload.locale,
+          },
+          channelContext,
+          {
+            subject,
+            html: preview.html,
+            text: preview.text ?? "",
+            ...sender,
+            attachments: mailAttachments,
+          },
+        );
+        sentStatus = result.status;
+      } catch (error) {
+        // Class and code only: the message can carry the address or a provider response body.
+        ctx.log?.warn("template test mail: channel threw", {
+          tenantId: event.user.tenantId,
+          errorClass: error instanceof Error ? error.name : typeof error,
+          errorCode: errorCodeOf(error),
+        });
+        return testMailFailed("channel_error");
+      }
+      if (sentStatus !== "sent") {
+        ctx.log?.warn("template test mail: channel did not send", {
+          tenantId: event.user.tenantId,
+          status: sentStatus,
+        });
+        return testMailFailed("not_sent");
+      }
+      return { isSuccess: true as const, data: { subject, checks: preview.checks } };
+    },
+  });
+}