@firedrill-tools/resend 0.1.1

package/firedrill/tools/resend/lib/wire.mjs

@@ -0,0 +1,98 @@
+// Pure HTTP wire helpers: snake_case → canonical argument mapping, Idempotency-Key handling and Resend's error
+// envelope `{ statusCode, message, name }`. No state, no clock. HTTP statuses are declared per route in the manifest.
+
+const ERRORS = new Map([
+  ["VALIDATION_ERROR", [422, "validation_error"]],
+  ["MISSING_REQUIRED_FIELD", [422, "missing_required_field"]],
+  ["INVALID_PARAMETER", [422, "invalid_parameter"]],
+  ["INVALID_IDEMPOTENCY_KEY", [400, "invalid_idempotency_key"]],
+  ["RESTRICTED_API_KEY", [401, "restricted_api_key"]],
+  ["INVALID_API_KEY", [403, "invalid_api_key"]],
+  ["DOMAIN_NOT_VERIFIED", [403, "validation_error"]],
+  ["NOT_FOUND", [404, "not_found"]],
+  ["DAILY_QUOTA_EXCEEDED", [429, "daily_quota_exceeded"]],
+  ["RATE_LIMIT_EXCEEDED", [429, "rate_limit_exceeded"]],
+  ["APPLICATION_ERROR", [500, "application_error"]],
+]);
+
+export const ERROR_STATUS = ERRORS;
+
+function last(values) {
+  return Array.isArray(values) && values.length > 0 ? values[values.length - 1] : undefined;
+}
+
+export function header(request, name) {
+  return last(request.headers[name]);
+}
+
+export function query(request, name) {
+  return last(request.query[name]);
+}
+
+export function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function jsonObject(request) {
+  return request.body.kind === "json" && isPlainObject(request.body.value) ? request.body.value : {};
+}
+
+/** Copy `[wireName, argumentName]` pairs that are present in `source` (own properties only) into `target`. */
+export function pick(source, pairs, target = {}) {
+  for (const [wire, name] of pairs) {
+    if (Object.hasOwn(source, wire) && source[wire] !== undefined) target[name] = source[wire];
+  }
+  return target;
+}
+
+/** Pagination query parameters: raw strings; the handler validates them and answers Resend's 422. */
+export function pageArguments(request, target = {}) {
+  for (const name of ["limit", "after", "before"]) {
+    const value = query(request, name);
+    if (value !== undefined) target[name] = value;
+  }
+  return target;
+}
+
+/**
+ * `Idempotency-Key`: 1–128 characters become the framework idempotency key; 129–256 characters are accepted without
+ * deduplication (the framework's evidence records keys up to 128 characters); an empty or longer key travels as an
+ * argument so the handler answers 400 `invalid_idempotency_key`.
+ */
+export function operationInput(request, args) {
+  const key = header(request, "idempotency-key");
+  if (key === undefined) return { arguments: args };
+  if (key.length >= 1 && key.length <= 128) return { arguments: args, idempotencyKey: key };
+  if (key.length >= 1 && key.length <= 256) return { arguments: args };
+  return { arguments: { ...args, idempotencyKey: key } };
+}
+
+/** Contacts accept a UUID or an e-mail address in the same path position. */
+export function contactRef(value, idName, target = {}) {
+  if (typeof value === "string" && value.includes("@")) target.email = value;
+  else target[idName] = value;
+  return target;
+}
+
+export function resendError(outcome) {
+  const error = outcome.error ?? {};
+  const message = typeof error.message === "string" && error.message.length > 0 ? error.message : "Internal server error";
+  if (outcome.status === "denied") {
+    return { statusCode: 403, message: "This operation is not granted to the calling actor in this Firedrill world.", name: "invalid_access" };
+  }
+  if (outcome.status === "unsupported") return { statusCode: 404, message: "Not found", name: "not_found" };
+  // HTTP status of `invalid` outcomes is framework-owned (400), so the body keeps 400 to match it.
+  if (outcome.status === "invalid") return { statusCode: 400, message: `Invalid request: ${message}`, name: "validation_error" };
+  const code = String(error.code ?? "").replace(/^tool\./, "");
+  const [statusCode, name] = ERRORS.get(code) ?? [500, "application_error"];
+  return { statusCode, message, name };
+}
+
+export function encodeOutcome({ outcome }) {
+  if (outcome.status === "ok") return { body: { kind: "json", value: outcome.value } };
+  const body = resendError(outcome);
+  const headers = body.name === "rate_limit_exceeded"
+    ? { "ratelimit-limit": "10", "ratelimit-remaining": "0", "ratelimit-reset": "1", "retry-after": "1" }
+    : undefined;
+  return { ...(headers === undefined ? {} : { headers }), body: { kind: "json", value: body } };
+}

package/firedrill/tools/resend/ops/contacts.mjs

@@ -0,0 +1,199 @@
+// Team-wide contacts with segment membership (pairs in `segment-members` and `contact-segments`).
+import { checkIdempotencyKey, fail, newId, normalizeUuid, requireUuid, resolveKey, scanAll } from "../lib/core.mjs";
+import { parseAddress, present, safeObject } from "../lib/check.mjs";
+import { paginate } from "../lib/page.mjs";
+import { wireTime } from "../lib/time.mjs";
+import { renderSegment } from "./keys-segments.mjs";
+
+const PROPERTY_KEY = /^[a-z][a-z0-9_]{0,49}$/;
+
+/** A bare e-mail address (no display name), lowercased, or `null`. */
+function plainAddress(value) {
+  if (typeof value !== "string") return null;
+  const parsed = parseAddress(value);
+  return parsed === null || parsed.address !== value.trim() ? null : parsed.address.toLowerCase();
+}
+
+function nameField(context, input, field, label) {
+  if (!Object.hasOwn(input, field)) return undefined;
+  const value = input[field];
+  if (value === null) return null;
+  if (typeof value !== "string" || value.length > 100) fail(context, "VALIDATION_ERROR", `The \`${label}\` field must be at most 100 characters.`);
+  return value;
+}
+
+function mergeProperties(context, base, patch) {
+  const source = safeObject(context, patch, "properties", 20);
+  const merged = { ...base };
+  for (const key of Object.keys(source)) {
+    const value = source[key];
+    const ok = PROPERTY_KEY.test(key) && (value === null || (typeof value === "number" && Number.isFinite(value)) || (typeof value === "string" && value.length <= 500));
+    if (!ok) fail(context, "VALIDATION_ERROR", "Contact properties need lowercase keys and string (≤ 500 characters), number or null values.");
+    merged[key] = value;
+  }
+  if (Object.keys(merged).length > 20) fail(context, "VALIDATION_ERROR", "A contact can hold at most 20 properties.");
+  return merged;
+}
+
+function locate(context, input, idField) {
+  const hasId = present(input[idField]);
+  const hasEmail = present(input.email);
+  if (hasId && hasEmail) fail(context, "INVALID_PARAMETER", `Provide either \`${idField === "id" ? "id" : "contact_id"}\` or \`email\`, not both.`);
+  if (!hasId && !hasEmail) fail(context, "MISSING_REQUIRED_FIELD", "Missing `id` or `email` field.");
+  let id;
+  if (hasId) {
+    id = requireUuid(context, input[idField], idField === "id" ? "id" : "contact_id");
+  } else {
+    const email = plainAddress(input.email);
+    if (email === null) fail(context, "INVALID_PARAMETER", "The `email` must be a valid email address.");
+    const index = context.state.get("contact-emails", email);
+    if (index === null) fail(context, "NOT_FOUND", "Contact not found");
+    id = index.contactId;
+  }
+  const contact = context.state.get("contacts", id);
+  if (contact === null) fail(context, "NOT_FOUND", "Contact not found");
+  return contact;
+}
+
+function locateSegment(context, raw) {
+  if (!present(raw)) fail(context, "MISSING_REQUIRED_FIELD", "Missing `segment_id` field.");
+  const id = requireUuid(context, raw, "segment_id");
+  const segment = context.state.get("segments", id);
+  if (segment === null) fail(context, "NOT_FOUND", "Segment not found");
+  return segment;
+}
+
+function join(context, contactId, segmentId, nowUs) {
+  context.state.put("segment-members", `${segmentId}/${contactId}`, { segmentId, contactId, addedAtUs: nowUs });
+  context.state.put("contact-segments", `${contactId}/${segmentId}`, { segmentId, contactId });
+}
+
+function summary(contact) {
+  return { id: contact.id, email: contact.email, first_name: contact.firstName, last_name: contact.lastName, created_at: wireTime(contact.createdAtUs), unsubscribed: contact.unsubscribed };
+}
+
+export function contactsCreate(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  if (!present(input.email)) fail(context, "MISSING_REQUIRED_FIELD", "Missing `email` field.");
+  const email = plainAddress(input.email);
+  if (email === null) fail(context, "VALIDATION_ERROR", "Invalid `email` field. The email address needs to follow the `email@example.com` format.");
+  for (const [field, label] of [["topics", "topics"], ["audienceId", "audience_id"]]) {
+    if (present(input[field])) fail(context, "VALIDATION_ERROR", `The \`${label}\` field is not supported by this simulated service.`);
+  }
+  const firstName = nameField(context, input, "firstName", "first_name") ?? null;
+  const lastName = nameField(context, input, "lastName", "last_name") ?? null;
+  const properties = present(input.properties) ? mergeProperties(context, {}, input.properties) : {};
+  const segmentIds = [];
+  if (present(input.segmentIds)) {
+    if (!Array.isArray(input.segmentIds) || input.segmentIds.length > 20) fail(context, "VALIDATION_ERROR", "The `segments` field accepts at most 20 segments.");
+    for (const raw of input.segmentIds) {
+      const id = normalizeUuid(raw);
+      if (id === null || context.state.get("segments", id) === null) fail(context, "VALIDATION_ERROR", "Every entry of `segments` must name an existing segment.");
+      if (!segmentIds.includes(id)) segmentIds.push(id);
+    }
+  }
+  if (context.state.get("contact-emails", email) !== null) fail(context, "VALIDATION_ERROR", "Contact already exists");
+  const id = newId(context, "contacts");
+  const nowUs = context.clock.nowUs();
+  context.state.put("contacts", id, { id, email, firstName, lastName, unsubscribed: input.unsubscribed === true, properties, createdAtUs: nowUs });
+  context.state.put("contact-emails", email, { contactId: id });
+  for (const segmentId of segmentIds) join(context, id, segmentId, nowUs);
+  return { object: "contact", id };
+}
+
+export function contactsList(input, context) {
+  resolveKey(context);
+  let query = null;
+  if (present(input.query)) {
+    if (input.query.length > 200 || input.query.includes("�")) fail(context, "VALIDATION_ERROR", "The `query` parameter is invalid.");
+    query = input.query.trim().toLowerCase();
+  }
+  let rows;
+  if (present(input.segmentId)) {
+    const segment = locateSegment(context, input.segmentId);
+    rows = scanAll(context, "segment-members", `${segment.id}/`).map((member) => context.state.get("contacts", member.value.contactId)).filter((contact) => contact !== null);
+  } else {
+    rows = scanAll(context, "contacts").map((record) => record.value);
+  }
+  if (query !== null) {
+    rows = rows.filter((contact) => [contact.email, contact.firstName ?? "", contact.lastName ?? ""].some((text) => text.toLowerCase().includes(query)));
+  }
+  return paginate(context, input, rows, summary);
+}
+
+export function contactsGet(input, context) {
+  resolveKey(context);
+  const contact = locate(context, input, "id");
+  return { object: "contact", ...summary(contact), properties: contact.properties };
+}
+
+export function contactsUpdate(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  const contact = locate(context, input, "id");
+  const next = { ...contact };
+  const firstName = nameField(context, input, "firstName", "first_name");
+  const lastName = nameField(context, input, "lastName", "last_name");
+  if (firstName !== undefined) next.firstName = firstName;
+  if (lastName !== undefined) next.lastName = lastName;
+  if (Object.hasOwn(input, "unsubscribed") && input.unsubscribed !== null) next.unsubscribed = input.unsubscribed === true;
+  if (present(input.properties)) next.properties = mergeProperties(context, contact.properties, input.properties);
+  if (present(input.newEmail)) {
+    const email = plainAddress(input.newEmail);
+    if (email === null) fail(context, "VALIDATION_ERROR", "Invalid `email` field. The email address needs to follow the `email@example.com` format.");
+    if (email !== contact.email) {
+      if (context.state.get("contact-emails", email) !== null) fail(context, "VALIDATION_ERROR", "Contact already exists");
+      context.state.delete("contact-emails", contact.email);
+      context.state.put("contact-emails", email, { contactId: contact.id });
+      next.email = email;
+    }
+  }
+  context.state.put("contacts", contact.id, next);
+  return { object: "contact", id: contact.id };
+}
+
+export function contactsRemove(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  const contact = locate(context, input, "id");
+  for (const link of scanAll(context, "contact-segments", `${contact.id}/`)) {
+    context.state.delete("contact-segments", link.rowId);
+    context.state.delete("segment-members", `${link.value.segmentId}/${contact.id}`);
+  }
+  context.state.delete("contact-emails", contact.email);
+  context.state.delete("contacts", contact.id);
+  return { object: "contact", id: contact.id, deleted: true };
+}
+
+export function contactsAddSegment(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  const contact = locate(context, input, "contactId");
+  const segment = locateSegment(context, input.segmentId);
+  if (context.state.get("contact-segments", `${contact.id}/${segment.id}`) === null) {
+    join(context, contact.id, segment.id, context.clock.nowUs());
+  }
+  return { object: "contact_segment", contact_id: contact.id, segment_id: segment.id };
+}
+
+export function contactsRemoveSegment(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  const contact = locate(context, input, "contactId");
+  const segment = locateSegment(context, input.segmentId);
+  if (!context.state.delete("contact-segments", `${contact.id}/${segment.id}`)) {
+    fail(context, "NOT_FOUND", "Contact is not a member of this segment");
+  }
+  context.state.delete("segment-members", `${segment.id}/${contact.id}`);
+  return { object: "contact_segment", contact_id: contact.id, segment_id: segment.id, deleted: true };
+}
+
+export function contactsListSegments(input, context) {
+  resolveKey(context);
+  const contact = locate(context, input, "contactId");
+  const rows = scanAll(context, "contact-segments", `${contact.id}/`)
+    .map((link) => context.state.get("segments", link.value.segmentId))
+    .filter((segment) => segment !== null);
+  return paginate(context, input, rows, renderSegment);
+}

package/firedrill/tools/resend/ops/domains.mjs

@@ -0,0 +1,125 @@
+// Domains: create with generated DNS records, list, get, instant synthetic verification, remove.
+import { checkIdempotencyKey, fail, newId, randomChars, requireUuid, resolveKey, scanAll } from "../lib/core.mjs";
+import { present, safeObject } from "../lib/check.mjs";
+import { paginate } from "../lib/page.mjs";
+import { wireTime } from "../lib/time.mjs";
+
+const REGIONS = ["us-east-1", "eu-west-1", "sa-east-1", "ap-northeast-1"];
+const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+function oneOf(context, value, allowed, field, fallback) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    fail(context, "VALIDATION_ERROR", `The \`${field}\` field must be one of: ${allowed.join(", ")}.`);
+  }
+  return value;
+}
+
+export function validHostname(name) {
+  if (name.length < 4 || name.length > 253) return false;
+  const labels = name.split(".");
+  return labels.length >= 2 && labels.every((label) => LABEL.test(label)) && !/^[0-9]+$/.test(labels[labels.length - 1]);
+}
+
+function getDomain(context, rawId) {
+  const id = requireUuid(context, rawId);
+  const domain = context.state.get("domains", id);
+  if (domain === null) fail(context, "NOT_FOUND", "Domain not found");
+  return domain;
+}
+
+function renderRecord(record) {
+  const out = { record: record.record, name: record.name, type: record.type, ttl: record.ttl, status: record.status, value: record.value };
+  if (record.priority !== null) out.priority = record.priority;
+  return out;
+}
+
+function summary(domain) {
+  return {
+    id: domain.id,
+    name: domain.name,
+    status: domain.status,
+    created_at: wireTime(domain.createdAtUs),
+    region: domain.region,
+    open_tracking: domain.openTracking,
+    click_tracking: domain.clickTracking,
+    capabilities: domain.capabilities,
+  };
+}
+
+export function domainsCreate(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  if (!present(input.name)) fail(context, "MISSING_REQUIRED_FIELD", "Missing `name` field.");
+  const name = input.name.trim().toLowerCase();
+  if (!validHostname(name)) fail(context, "VALIDATION_ERROR", "The `name` field must be a valid domain name.");
+  if (present(input.trackingSubdomain)) fail(context, "VALIDATION_ERROR", "The `tracking_subdomain` field is not supported by this simulated service.");
+  const region = oneOf(context, input.region, REGIONS, "region", "us-east-1");
+  const tls = oneOf(context, input.tls, ["opportunistic", "enforced"], "tls", "opportunistic");
+  let customReturnPath = "send";
+  if (present(input.customReturnPath)) {
+    customReturnPath = String(input.customReturnPath).toLowerCase();
+    if (customReturnPath.length > 63 || !LABEL.test(customReturnPath)) fail(context, "VALIDATION_ERROR", "The `custom_return_path` field must be a single DNS label.");
+  }
+  const capabilities = { sending: "enabled", receiving: "disabled" };
+  if (present(input.capabilities)) {
+    const source = safeObject(context, input.capabilities, "capabilities", 2);
+    for (const key of Object.keys(source)) {
+      if (key !== "sending" && key !== "receiving") fail(context, "VALIDATION_ERROR", "The `capabilities` field accepts only `sending` and `receiving`.");
+      capabilities[key] = oneOf(context, source[key], ["enabled", "disabled"], `capabilities.${key}`, capabilities[key]);
+    }
+  }
+  if (context.state.get("domain-names", name) !== null) fail(context, "VALIDATION_ERROR", `The ${name} domain has been registered already`);
+  const id = newId(context, "domains");
+  const host = `${customReturnPath}.${name}`;
+  const records = [
+    { record: "SPF", name: host, type: "MX", ttl: "Auto", status: "not_started", value: `feedback-smtp.${region}.amazonses.com`, priority: 10 },
+    { record: "SPF", name: host, type: "TXT", ttl: "Auto", status: "not_started", value: '"v=spf1 include:amazonses.com ~all"', priority: null },
+    { record: "DKIM", name: `resend._domainkey.${name}`, type: "TXT", ttl: "Auto", status: "not_started", value: `p=${randomChars(context, B64, 216)}`, priority: null },
+  ];
+  if (capabilities.receiving === "enabled") {
+    records.push({ record: "Receiving", name, type: "MX", ttl: "Auto", status: "not_started", value: `inbound-smtp.${region}.amazonaws.com`, priority: 10 });
+  }
+  const domain = {
+    id, name, region, status: "not_started",
+    openTracking: input.openTracking === true, clickTracking: input.clickTracking === true,
+    tls, customReturnPath, capabilities, records, createdAtUs: context.clock.nowUs(),
+  };
+  context.state.put("domains", id, domain);
+  context.state.put("domain-names", name, { domainId: id });
+  const { capabilities: caps, ...rest } = summary(domain);
+  return { ...rest, capabilities: caps, records: records.map(renderRecord) };
+}
+
+export function domainsList(input, context) {
+  resolveKey(context);
+  const rows = scanAll(context, "domains").map((record) => record.value);
+  return paginate(context, input, rows, summary);
+}
+
+export function domainsGet(input, context) {
+  resolveKey(context);
+  const domain = getDomain(context, input.id);
+  return { object: "domain", ...summary(domain), records: domain.records.map(renderRecord) };
+}
+
+export function domainsVerify(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  const domain = getDomain(context, input.id);
+  if (domain.status !== "verified") {
+    const status = domain.name.endsWith(".invalid") ? "failed" : "verified";
+    context.state.put("domains", domain.id, { ...domain, status, records: domain.records.map((record) => ({ ...record, status })) });
+  }
+  return { object: "domain", id: domain.id };
+}
+
+export function domainsRemove(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  const domain = getDomain(context, input.id);
+  context.state.delete("domains", domain.id);
+  context.state.delete("domain-names", domain.name);
+  return { object: "domain", id: domain.id, deleted: true };
+}

package/firedrill/tools/resend/ops/email-model.mjs

@@ -0,0 +1,100 @@
+// Email validation, the synthetic delivery rule and wire rendering shared by the email operations.
+import { fail } from "../lib/core.mjs";
+import { addressList, boundedString, parseAddress, present, rejectPresent, safeObject, utf8Bytes } from "../lib/check.mjs";
+import { parseTimestamp, US_PER_DAY, wireTime } from "../lib/time.mjs";
+
+const TAG = /^[A-Za-z0-9_-]{1,256}$/;
+const MAX_BODY_BYTES = 512_000;
+export const MAX_SCHEDULE_US = 30 * US_PER_DAY;
+
+/** A recipient in the reserved `.invalid` TLD makes the synthetic delivery bounce. */
+export function bounces(record) {
+  return [...record.to, ...record.cc, ...record.bcc].some((entry) => {
+    const parsed = parseAddress(entry);
+    return parsed !== null && (parsed.domain === "invalid" || parsed.domain.endsWith(".invalid"));
+  });
+}
+
+/** `last_event` as a reader sees it at `nowUs`: a due scheduled email renders its synthetic outcome. */
+export function lastEvent(record, nowUs) {
+  if (record.status === "scheduled" && record.scheduledAtUs !== null && record.scheduledAtUs <= nowUs) {
+    return bounces(record) ? "bounced" : "delivered";
+  }
+  return record.status;
+}
+
+export function scheduleTime(context, raw, field = "scheduled_at") {
+  const at = parseTimestamp(raw);
+  const now = context.clock.nowUs();
+  if (at === null) fail(context, "VALIDATION_ERROR", `The \`${field}\` field must be an ISO 8601 timestamp with a time zone.`);
+  if (at <= now) fail(context, "VALIDATION_ERROR", `The \`${field}\` field must be in the future.`);
+  if (at > now + MAX_SCHEDULE_US) fail(context, "VALIDATION_ERROR", `The \`${field}\` field must be within 30 days.`);
+  return at;
+}
+
+/** Validate one send input (canonical camelCase). `where` prefixes messages inside a batch. */
+export function validateSend(context, input, { batch = false, index = 0 } = {}) {
+  const at = batch ? `emails[${index}]: ` : "";
+  const scoped = (code, message) => fail(context, code, at + message);
+  if (typeof input !== "object" || input === null || Array.isArray(input)) scoped("VALIDATION_ERROR", "Each email must be an object.");
+  rejectPresent({ fail: (o) => scoped(o.code, o.message) }, input, ["attachments", "template", "topicId"], (field) => `The \`${field}\` field is not supported by this simulated service.`);
+  if (batch && present(input.scheduledAt)) scoped("VALIDATION_ERROR", "`scheduled_at` is not supported in batch");
+  if (!present(input.from)) scoped("MISSING_REQUIRED_FIELD", "Missing `from` field.");
+  const sender = parseAddress(input.from);
+  if (sender === null) scoped("VALIDATION_ERROR", "Invalid `from` field. The email address needs to follow the `email@example.com` or `Name <email@example.com>` format.");
+  const wrap = { fail: (o) => scoped(o.code, o.message) };
+  const to = addressList(wrap, input.to, "to", { required: true });
+  const cc = addressList(wrap, input.cc, "cc");
+  const bcc = addressList(wrap, input.bcc, "bcc");
+  const replyTo = addressList(wrap, input.replyTo, "reply_to");
+  if (!present(input.subject)) scoped("MISSING_REQUIRED_FIELD", "Missing `subject` field.");
+  boundedString(wrap, input.subject, "subject", { max: 998 });
+  const html = typeof input.html === "string" && input.html.length > 0 ? input.html : null;
+  const text = typeof input.text === "string" && input.text.length > 0 ? input.text : null;
+  if (html === null && text === null) scoped("MISSING_REQUIRED_FIELD", "Missing `html` or `text` field.");
+  for (const [name, body] of [["html", html], ["text", text]]) {
+    if (body !== null && utf8Bytes(body) > MAX_BODY_BYTES) scoped("VALIDATION_ERROR", `The \`${name}\` field exceeds ${MAX_BODY_BYTES} bytes.`);
+  }
+  const headers = {};
+  if (present(input.headers)) {
+    const source = safeObject(wrap, input.headers, "headers", 30);
+    for (const name of Object.keys(source)) {
+      if (!/^[!-9;-~]{1,256}$/.test(name) || typeof source[name] !== "string" || source[name].length > 998) {
+        scoped("VALIDATION_ERROR", "The `headers` field must map header names to string values.");
+      }
+      headers[name] = source[name];
+    }
+  }
+  const tags = [];
+  if (present(input.tags)) {
+    if (!Array.isArray(input.tags) || input.tags.length > 10) scoped("VALIDATION_ERROR", "The `tags` field must be an array of at most 10 tags.");
+    for (const tag of input.tags) {
+      const ok = typeof tag === "object" && tag !== null && typeof tag.name === "string" && typeof tag.value === "string" && TAG.test(tag.name) && TAG.test(tag.value);
+      if (!ok) scoped("VALIDATION_ERROR", "Tags should only contain ASCII letters, numbers, underscores, or dashes.");
+      tags.push({ name: tag.name, value: tag.value });
+    }
+  }
+  const scheduledAtUs = !batch && present(input.scheduledAt) ? scheduleTime(context, input.scheduledAt) : null;
+  return { from: input.from.trim(), fromDomain: sender.domain, to, cc, bcc, replyTo, subject: input.subject, html, text, headers, tags, scheduledAtUs };
+}
+
+export function renderListItem(record, nowUs) {
+  return {
+    object: "email",
+    id: record.id,
+    to: record.to,
+    from: record.from,
+    created_at: wireTime(record.createdAtUs),
+    subject: record.subject,
+    bcc: record.bcc,
+    cc: record.cc,
+    reply_to: record.replyTo,
+    last_event: lastEvent(record, nowUs),
+    scheduled_at: wireTime(record.scheduledAtUs),
+  };
+}
+
+export function renderEmail(record, nowUs) {
+  const base = renderListItem(record, nowUs);
+  return { ...base, html: record.html, text: record.text, tags: record.tags };
+}

package/firedrill/tools/resend/ops/emails.mjs

@@ -0,0 +1,139 @@
+// Emails: synthetic send and batch send, list, get, reschedule and cancel.
+import { checkIdempotencyKey, fail, newId, randomChars, requireUuid, resolveKey, scanAll } from "../lib/core.mjs";
+import { present } from "../lib/check.mjs";
+import { paginate } from "../lib/page.mjs";
+import { utcDay, wireTime } from "../lib/time.mjs";
+import { bounces, lastEvent, renderEmail, renderListItem, scheduleTime, validateSend } from "./email-model.mjs";
+
+const STATUSES = ["delivered", "bounced", "scheduled", "canceled", "sent"];
+
+function sendingDomain(context, key, fromDomain) {
+  if (key.permission === "sending_access" && key.domainId !== null) {
+    const allowed = context.state.get("domains", key.domainId);
+    if (allowed === null || allowed.name !== fromDomain) {
+      const label = allowed === null ? "its configured domain" : allowed.name;
+      fail(context, "DOMAIN_NOT_VERIFIED", `This API key is restricted to send emails from ${label} only`);
+    }
+  }
+  const index = context.state.get("domain-names", fromDomain);
+  const domain = index === null ? null : context.state.get("domains", index.domainId);
+  if (domain === null || domain.status !== "verified" || domain.capabilities.sending !== "enabled") {
+    fail(context, "DOMAIN_NOT_VERIFIED", `The ${fromDomain} domain is not verified. Please, add and verify your domain.`);
+  }
+}
+
+function reserveQuota(context, team, count) {
+  const now = context.clock.nowUs();
+  const today = utcDay(now);
+  const usage = context.state.get("meta", "usage");
+  const sent = usage !== null && usage.day === today ? usage.sent : 0;
+  if (sent + count > team.dailyQuota) fail(context, "DAILY_QUOTA_EXCEEDED", "You have reached your daily email sending quota.");
+  context.state.put("meta", "usage", { day: today, sent: sent + count });
+}
+
+function accept(context, key, email, batchId) {
+  const id = newId(context, "emails");
+  const nowUs = context.clock.nowUs();
+  const { fromDomain, ...fields } = email;
+  const immediate = email.scheduledAtUs === null;
+  const status = immediate ? (bounces(email) ? "bounced" : "delivered") : "scheduled";
+  const record = { id, ...fields, createdAtUs: nowUs, status, apiKeyId: key.id, batchId };
+  context.state.put("emails", id, record);
+  if (immediate) {
+    const createdAt = wireTime(nowUs);
+    context.events.emit("email.sent", { email_id: id, from: email.from, to: email.to, subject: email.subject, created_at: createdAt, batch_id: batchId });
+    if (status === "bounced") {
+      context.events.emit("email.bounced", { email_id: id, to: email.to, created_at: createdAt, bounce: { type: "Permanent", message: "Recipient address does not exist" } });
+    } else {
+      context.events.emit("email.delivered", { email_id: id, to: email.to, created_at: createdAt });
+    }
+  }
+  return id;
+}
+
+function touchKey(context, key) {
+  context.state.put("api-keys", key.id, { ...key, lastUsedAtUs: context.clock.nowUs() });
+}
+
+export function emailsSend(input, context) {
+  const { key, team } = resolveKey(context, { send: true });
+  checkIdempotencyKey(context, input);
+  const email = validateSend(context, input);
+  sendingDomain(context, key, email.fromDomain);
+  reserveQuota(context, team, 1);
+  const id = accept(context, key, email, null);
+  touchKey(context, key);
+  return { id };
+}
+
+export function emailsSendBatch(input, context) {
+  const { key, team } = resolveKey(context, { send: true });
+  checkIdempotencyKey(context, input);
+  if (present(input.batchValidation)) fail(context, "VALIDATION_ERROR", "The `x-batch-validation: permissive` mode is not supported by this simulated service.");
+  if (!Array.isArray(input.emails)) fail(context, "VALIDATION_ERROR", "The request body must be an array of emails.");
+  if (input.emails.length === 0 || input.emails.length > 100) fail(context, "VALIDATION_ERROR", "A batch must contain between 1 and 100 emails.");
+  const emails = input.emails.map((entry, index) => validateSend(context, entry, { batch: true, index }));
+  for (const email of emails) sendingDomain(context, key, email.fromDomain);
+  reserveQuota(context, team, emails.length);
+  const hex = randomChars(context, "0123456789abcdef", 32);
+  const batchId = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+  const data = emails.map((email) => ({ id: accept(context, key, email, batchId) }));
+  touchKey(context, key);
+  return { data };
+}
+
+export function emailsList(input, context) {
+  resolveKey(context);
+  const nowUs = context.clock.nowUs();
+  let query = null;
+  if (present(input.query)) {
+    if (input.query.length > 200 || input.query.includes("�")) fail(context, "VALIDATION_ERROR", "The `query` parameter is invalid.");
+    query = input.query.trim().toLowerCase();
+  }
+  if (present(input.status) && !STATUSES.includes(input.status)) {
+    fail(context, "VALIDATION_ERROR", `The \`status\` parameter must be one of: ${STATUSES.join(", ")}.`);
+  }
+  const rows = scanAll(context, "emails")
+    .map((record) => record.value)
+    .filter((email) => !present(input.status) || lastEvent(email, nowUs) === input.status)
+    .filter((email) => query === null || email.subject.toLowerCase().includes(query) || email.to.some((to) => to.toLowerCase().includes(query)));
+  return paginate(context, input, rows, (email) => renderListItem(email, nowUs));
+}
+
+function getEmail(context, rawId) {
+  const id = requireUuid(context, rawId);
+  const email = context.state.get("emails", id);
+  if (email === null) fail(context, "NOT_FOUND", "Email not found");
+  return email;
+}
+
+export function emailsGet(input, context) {
+  resolveKey(context);
+  return renderEmail(getEmail(context, input.id), context.clock.nowUs());
+}
+
+function pendingScheduled(context, email, verb) {
+  if (lastEvent(email, context.clock.nowUs()) !== "scheduled") {
+    fail(context, "VALIDATION_ERROR", `Email cannot be ${verb} because it is not scheduled`);
+  }
+}
+
+export function emailsUpdate(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  const email = getEmail(context, input.id);
+  if (!present(input.scheduledAt)) fail(context, "MISSING_REQUIRED_FIELD", "Missing `scheduled_at` field.");
+  pendingScheduled(context, email, "updated");
+  const scheduledAtUs = scheduleTime(context, input.scheduledAt);
+  context.state.put("emails", email.id, { ...email, scheduledAtUs });
+  return { object: "email", id: email.id };
+}
+
+export function emailsCancel(input, context) {
+  resolveKey(context);
+  checkIdempotencyKey(context, input);
+  const email = getEmail(context, input.id);
+  pendingScheduled(context, email, "canceled");
+  context.state.put("emails", email.id, { ...email, status: "canceled" });
+  return { object: "email", id: email.id };
+}