@marlinjai/mail-contract 0.2.0 → 0.4.0

package/dist/index.mjs

@@ -114,6 +114,8 @@ var IDEMPOTENCY_KEY_MAX_LENGTH = 255;
 var IDEMPOTENCY_KEY_RETENTION_HOURS = 24;
 var SUBJECT_HEADER = "x-mail-subject";
 var WORKSPACE_HEADER = "x-mail-workspace";
+var ON_BEHALF_OF_HEADER = "x-mail-on-behalf-of";
+var ON_BEHALF_OF_MAX_LENGTH = 200;
 var REQUEST_ID_HEADER = "x-request-id";
 var RETRY_AFTER_HEADER = "retry-after";
 var API_VERSION_PREFIX = "/v1";
@@ -437,7 +439,12 @@ var Mailing = z5.object({
   /** The template the document was taken from, if any. The snapshot is what is sent. */
   template_id: Id.nullable(),
   document: TemplateDocument,
-  topic: Slug,
+  /**
+   * The topic the mailing is sent under. Null for a letter (a one-to-one
+   * mailing with at most one recipient, which belongs to no topic and whose
+   * unsubscribe link offers every topic) and for an automation's notification.
+   */
+  topic: Slug.nullable(),
   provider_id: Id,
   status: MailingStatus,
   counts: MailingCounts,
@@ -462,7 +469,13 @@ var MailingContent = {
   name: z5.string().max(200).optional(),
   subject: z5.string().min(1).max(998),
   preheader: z5.string().max(500).optional(),
-  topic: Slug,
+  /**
+   * Omitted or null makes the mailing a letter: one recipient at most, sent to
+   * anybody not blocked on every topic, with an unsubscribe link that offers
+   * every topic and no List-Unsubscribe headers. See "Letters" in the
+   * contract's documentation.
+   */
+  topic: Slug.nullable().optional(),
   provider_id: Id,
   metadata: MailingMetadata.optional()
 };
@@ -478,7 +491,8 @@ var MailingUpdate = z5.object({
   name: z5.string().max(200).nullable().optional(),
   subject: MailingContent.subject.optional(),
   preheader: z5.string().max(500).nullable().optional(),
-  topic: Slug.optional(),
+  /** Null turns a draft into a letter, which it can only be with at most one recipient. */
+  topic: Slug.nullable().optional(),
   provider_id: Id.optional(),
   metadata: MailingMetadata.optional(),
   document: TemplateDocument.optional()
@@ -526,6 +540,8 @@ var Recipient = z5.object({
   updated_at: Timestamp
 });
 var MAX_RECIPIENTS_PER_BATCH = 1e3;
+var MAX_LETTER_RECIPIENTS = 1;
+var LETTER_RECIPIENT_REFUSAL = "letter_has_one_recipient";
 var RecipientInput = z5.object({
   contact_id: Id.optional(),
   external_id: z5.string().min(1).max(255).optional(),
@@ -1906,10 +1922,45 @@ var EventListQuery = PageQuery.extend({
   contact_id: Id.optional()
 });
 
+// src/unsubscribe.ts
+var UNSUBSCRIBE_PATH_PREFIX = "/u/";
+var LIST_UNSUBSCRIBE_POST_VALUE = "List-Unsubscribe=One-Click";
+var RESERVED_MERGE_FIELDS = {
+  /** From the recipient's merge values, else the contact. Supports a fallback. */
+  first_name: { source: "contact", fallback: true, required_for_broadcast: false },
+  last_name: { source: "contact", fallback: true, required_for_broadcast: false },
+  email: { source: "contact", fallback: false, required_for_broadcast: false },
+  /** The hosted unsubscribe page for this recipient. A broadcast without it is refused. */
+  unsubscribe_url: { source: "service", fallback: false, required_for_broadcast: true }
+};
+var MERGE_FIELD_PATTERN = /\{\{\s*([a-z][a-z0-9_]*)\s*(?:\|([^}]*))?\}\}/g;
+function findMergeFields(html) {
+  const uses = [];
+  for (const match of html.matchAll(MERGE_FIELD_PATTERN)) {
+    uses.push({ name: match[1], fallback: match[2] === void 0 ? null : match[2].trim() });
+  }
+  return uses;
+}
+function missingRequiredMergeFields(html) {
+  const used = new Set(findMergeFields(html).map((u) => u.name));
+  return Object.keys(RESERVED_MERGE_FIELDS).filter(
+    (name) => RESERVED_MERGE_FIELDS[name].required_for_broadcast && !used.has(name)
+  );
+}
+
 // src/workspace.ts
 var CompanyId = z8.string().min(1).max(64);
 var ASSET_POLICIES = ["any", "service_only"];
 var AssetPolicy = z8.enum(ASSET_POLICIES);
+var MAX_ALLOWED_ASSET_HOSTS = 20;
+var AssetHost = z8.string().trim().toLowerCase().min(1).max(253).regex(/^(?=.{1,253}(?::\d{1,5})?$)[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+(:\d{1,5})?$/, "a host name such as example.com");
+var MAX_MERGE_DEFAULTS = 50;
+var MAX_MERGE_DEFAULT_LENGTH = 2e3;
+var MergeFieldName = z8.string().regex(/^[a-z][a-z0-9_]*$/, "a merge-field name: lowercase letters, digits and underscores, starting with a letter").max(64);
+var MergeDefaultValue = z8.union([z8.string().max(MAX_MERGE_DEFAULT_LENGTH), z8.number().finite(), z8.boolean()]);
+var MergeDefaults = z8.record(MergeFieldName, MergeDefaultValue).refine((m) => Object.keys(m).length <= MAX_MERGE_DEFAULTS, `at most ${MAX_MERGE_DEFAULTS} merge defaults`).refine((m) => !Object.keys(m).some((k) => k in RESERVED_MERGE_FIELDS), {
+  message: `a reserved merge field (${Object.keys(RESERVED_MERGE_FIELDS).join(", ")}) cannot have a workspace default`
+});
 var WorkspaceSettings = z8.object({
   /** Default language of the hosted unsubscribe page (BCP 47 tag, e.g. "de"). */
   default_locale: z8.string().min(2).max(35),
@@ -1919,6 +1970,14 @@ var WorkspaceSettings = z8.object({
   tracking_enabled: z8.boolean(),
   /** Where images, stylesheets and fonts in a mail may load from. `any` by default. */
   asset_policy: AssetPolicy,
+  /**
+   * Hosts a `service_only` workspace also allows, besides the service's own:
+   * the workspace's website, typically. Empty by default. Ignored under `any`,
+   * which allows everything already.
+   */
+  allowed_asset_hosts: z8.array(AssetHost).max(MAX_ALLOWED_ASSET_HOSTS),
+  /** Merge values every mail of the workspace can use (see `MergeDefaults`). Empty by default. */
+  merge_defaults: MergeDefaults,
   /**
    * The time zone an automation reads a wall clock in for a contact who has
    * none of their own (A1). Null falls back to UTC.
@@ -2020,6 +2079,7 @@ var AUDIT_ACTIONS = [
   "provider.anomaly_cleared",
   "topic.created",
   "topic.updated",
+  "topic.deleted",
   "template.created",
   "template.updated",
   "template.deleted",
@@ -2087,7 +2147,16 @@ var AUDIT_ACTIONS = [
 var AuditAction = z8.enum(AUDIT_ACTIONS);
 var AuditActor = z8.discriminatedUnion("type", [
   z8.object({ type: z8.literal("member"), member_id: Id, subject: z8.string().min(1) }),
-  z8.object({ type: z8.literal("api_key"), api_key_id: Id }),
+  z8.object({
+    type: z8.literal("api_key"),
+    api_key_id: Id,
+    /**
+     * Who the client's application said it was acting for, from
+     * `ON_BEHALF_OF_HEADER`: reported by that application, never verified.
+     * Absent when the call carried no label.
+     */
+    on_behalf_of: z8.string().min(1).max(ON_BEHALF_OF_MAX_LENGTH).optional()
+  }),
   /** The service itself (the worker, a bounce, the hosted unsubscribe page). */
   z8.object({ type: z8.literal("system"), reason: z8.string().min(1).max(200) })
 ]);
@@ -2415,7 +2484,16 @@ var WEBHOOK_EVENT_TYPES = [
    * `webhook_events.type` is checked against it, not because an endpoint can ask
    * to receive everybody's.
    */
-  "automation.webhook"
+  "automation.webhook",
+  /**
+   * E4 of the embeddable-mail plan: a template changed, so a client that
+   * caches or mirrors templates (an app embedding the editor beside the
+   * hosted dashboard) can invalidate. The service stays the source of truth:
+   * the event carries the new version, never the document.
+   */
+  "template.created",
+  "template.updated",
+  "template.deleted"
 ];
 var WebhookEventType = z12.enum(WEBHOOK_EVENT_TYPES);
 var MessageEventBase = z12.object({
@@ -2577,6 +2655,15 @@ var AutomationWebhookData = AutomationRunEventBase.extend({
   payload: JsonValue.nullable(),
   fired_at: Timestamp
 });
+var TemplateEventBase = z12.object({
+  template_id: Id,
+  name: z12.string().min(1).max(200),
+  version: z12.number().int().min(1),
+  source: z12.enum(["api", "dashboard", "mjml_import"])
+});
+var TemplateCreatedData = TemplateEventBase.extend({ created_at: Timestamp });
+var TemplateUpdatedData = TemplateEventBase.extend({ archived: z12.boolean(), updated_at: Timestamp });
+var TemplateDeletedData = TemplateEventBase.extend({ deleted_at: Timestamp });
 var envelope = (type, data) => z12.object({
   /** Unique per event: a receiver deduplicates on it (deliveries may repeat). */
   id: Id,
@@ -2604,7 +2691,10 @@ var WebhookEvent = z12.discriminatedUnion("type", [
   envelope("automation.run_completed", AutomationRunCompletedData),
   envelope("automation.run_exited", AutomationRunExitedData),
   envelope("automation.run_failed", AutomationRunFailedData),
-  envelope("automation.webhook", AutomationWebhookData)
+  envelope("automation.webhook", AutomationWebhookData),
+  envelope("template.created", TemplateCreatedData),
+  envelope("template.updated", TemplateUpdatedData),
+  envelope("template.deleted", TemplateDeletedData)
 ]);
 var WebhookEndpoint = z12.object({
   id: Id,
@@ -2727,32 +2817,6 @@ async function verifyWebhook(input) {
   return matched ? { ok: true, timestamp } : { ok: false, reason: "signature_mismatch" };
 }
 
-// src/unsubscribe.ts
-var UNSUBSCRIBE_PATH_PREFIX = "/u/";
-var LIST_UNSUBSCRIBE_POST_VALUE = "List-Unsubscribe=One-Click";
-var RESERVED_MERGE_FIELDS = {
-  /** From the recipient's merge values, else the contact. Supports a fallback. */
-  first_name: { source: "contact", fallback: true, required_for_broadcast: false },
-  last_name: { source: "contact", fallback: true, required_for_broadcast: false },
-  email: { source: "contact", fallback: false, required_for_broadcast: false },
-  /** The hosted unsubscribe page for this recipient. A broadcast without it is refused. */
-  unsubscribe_url: { source: "service", fallback: false, required_for_broadcast: true }
-};
-var MERGE_FIELD_PATTERN = /\{\{\s*([a-z][a-z0-9_]*)\s*(?:\|([^}]*))?\}\}/g;
-function findMergeFields(html) {
-  const uses = [];
-  for (const match of html.matchAll(MERGE_FIELD_PATTERN)) {
-    uses.push({ name: match[1], fallback: match[2] === void 0 ? null : match[2].trim() });
-  }
-  return uses;
-}
-function missingRequiredMergeFields(html) {
-  const used = new Set(findMergeFields(html).map((u) => u.name));
-  return Object.keys(RESERVED_MERGE_FIELDS).filter(
-    (name) => RESERVED_MERGE_FIELDS[name].required_for_broadcast && !used.has(name)
-  );
-}
-
 // src/billing.ts
 import { z as z13 } from "zod";
 var PLAN_IDS = ["free", "starter", "growth", "design_partner"];
@@ -3263,6 +3327,16 @@ var sendingRoutes = {
     access: "admin",
     phase: "S2"
   },
+  /** Refused with `conflict` while a mailing or an automation step still uses the topic; subscriptions and suppressions on it go with it. */
+  "topics.delete": {
+    method: "DELETE",
+    path: "/v1/topics/:id",
+    params: IdParams,
+    response: Ok,
+    status: 200,
+    access: "admin",
+    phase: "S2"
+  },
   "contacts.upsert": {
     method: "POST",
     path: "/v1/contacts",
@@ -4180,6 +4254,9 @@ function buildPath(path, params = {}) {
     return encodeURIComponent(String(value));
   });
 }
+function operationsWithAccess(access) {
+  return Object.entries(routes).filter(([, route]) => route.access === access).map(([id]) => id).sort();
+}
 function matchRoute(method, pathname) {
   for (const [id, route] of Object.entries(routes)) {
     if (route.method !== method) continue;
@@ -4230,6 +4307,7 @@ export {
   ApiKeyScope,
   Asset,
   AssetContentType,
+  AssetHost,
   AssetImport,
   AssetPolicy,
   AuditAction,
@@ -4379,11 +4457,13 @@ export {
   InviteListQuery,
   InviteStatus,
   JsonValue,
+  LETTER_RECIPIENT_REFUSAL,
   LIST_UNSUBSCRIBE_POST_VALUE,
   MAILING_ACTIONS,
   MAILING_KINDS,
   MAILING_STATUSES,
   MAILING_TRANSITIONS,
+  MAX_ALLOWED_ASSET_HOSTS,
   MAX_ASSET_BYTES,
   MAX_DELAY_SECONDS,
   MAX_DOCUMENT_BYTES,
@@ -4396,6 +4476,9 @@ export {
   MAX_IMPORT_URL_LENGTH,
   MAX_INVITE_TTL_DAYS,
   MAX_IN_LIST,
+  MAX_LETTER_RECIPIENTS,
+  MAX_MERGE_DEFAULTS,
+  MAX_MERGE_DEFAULT_LENGTH,
   MAX_MJML_DEPTH,
   MAX_MJML_ELEMENTS,
   MAX_MJML_IMPORT_BYTES,
@@ -4440,6 +4523,9 @@ export {
   MemberCreate,
   MemberRole,
   MemberUpdate,
+  MergeDefaultValue,
+  MergeDefaults,
+  MergeFieldName,
   Message,
   MessageFailedData,
   MessageListQuery,
@@ -4448,6 +4534,8 @@ export {
   MessageSummary,
   NotifyRecipients,
   NotifyStep,
+  ON_BEHALF_OF_HEADER,
+  ON_BEHALF_OF_MAX_LENGTH,
   OffsetDays,
   Ok,
   PLAN_FEATURES,
@@ -4525,6 +4613,8 @@ export {
   Template,
   TemplateCompileRequest,
   TemplateCreate,
+  TemplateCreatedData,
+  TemplateDeletedData,
   TemplateDocument,
   TemplateExportQuery,
   TemplateImport,
@@ -4534,6 +4624,7 @@ export {
   TemplateListQuery,
   TemplateSummary,
   TemplateUpdate,
+  TemplateUpdatedData,
   TemplateVersion,
   TemplateVersionParams,
   TimeOfDay,
@@ -4610,6 +4701,7 @@ export {
   matchRoute,
   missingRequiredMergeFields,
   nowSeconds,
+  operationsWithAccess,
   page,
   parseExportWarningsHeader,
   parseUsageWarningHeader,

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The v1 API contract of the mail service: zod schemas and types for every request, response, error and webhook, the route table, and webhook signing helpers",
   "license": "MIT",
   "repository": {