@marlinjai/mail-contract 0.2.0 → 0.4.0

package/dist/index.js

@@ -49,6 +49,7 @@ __export(index_exports, {
   ApiKeyScope: () => ApiKeyScope,
   Asset: () => Asset,
   AssetContentType: () => AssetContentType,
+  AssetHost: () => AssetHost,
   AssetImport: () => AssetImport,
   AssetPolicy: () => AssetPolicy,
   AuditAction: () => AuditAction,
@@ -198,11 +199,13 @@ __export(index_exports, {
   InviteListQuery: () => InviteListQuery,
   InviteStatus: () => InviteStatus,
   JsonValue: () => JsonValue,
+  LETTER_RECIPIENT_REFUSAL: () => LETTER_RECIPIENT_REFUSAL,
   LIST_UNSUBSCRIBE_POST_VALUE: () => LIST_UNSUBSCRIBE_POST_VALUE,
   MAILING_ACTIONS: () => MAILING_ACTIONS,
   MAILING_KINDS: () => MAILING_KINDS,
   MAILING_STATUSES: () => MAILING_STATUSES,
   MAILING_TRANSITIONS: () => MAILING_TRANSITIONS,
+  MAX_ALLOWED_ASSET_HOSTS: () => MAX_ALLOWED_ASSET_HOSTS,
   MAX_ASSET_BYTES: () => MAX_ASSET_BYTES,
   MAX_DELAY_SECONDS: () => MAX_DELAY_SECONDS,
   MAX_DOCUMENT_BYTES: () => MAX_DOCUMENT_BYTES,
@@ -215,6 +218,9 @@ __export(index_exports, {
   MAX_IMPORT_URL_LENGTH: () => MAX_IMPORT_URL_LENGTH,
   MAX_INVITE_TTL_DAYS: () => MAX_INVITE_TTL_DAYS,
   MAX_IN_LIST: () => MAX_IN_LIST,
+  MAX_LETTER_RECIPIENTS: () => MAX_LETTER_RECIPIENTS,
+  MAX_MERGE_DEFAULTS: () => MAX_MERGE_DEFAULTS,
+  MAX_MERGE_DEFAULT_LENGTH: () => MAX_MERGE_DEFAULT_LENGTH,
   MAX_MJML_DEPTH: () => MAX_MJML_DEPTH,
   MAX_MJML_ELEMENTS: () => MAX_MJML_ELEMENTS,
   MAX_MJML_IMPORT_BYTES: () => MAX_MJML_IMPORT_BYTES,
@@ -259,6 +265,9 @@ __export(index_exports, {
   MemberCreate: () => MemberCreate,
   MemberRole: () => MemberRole,
   MemberUpdate: () => MemberUpdate,
+  MergeDefaultValue: () => MergeDefaultValue,
+  MergeDefaults: () => MergeDefaults,
+  MergeFieldName: () => MergeFieldName,
   Message: () => Message,
   MessageFailedData: () => MessageFailedData,
   MessageListQuery: () => MessageListQuery,
@@ -267,6 +276,8 @@ __export(index_exports, {
   MessageSummary: () => MessageSummary,
   NotifyRecipients: () => NotifyRecipients,
   NotifyStep: () => NotifyStep,
+  ON_BEHALF_OF_HEADER: () => ON_BEHALF_OF_HEADER,
+  ON_BEHALF_OF_MAX_LENGTH: () => ON_BEHALF_OF_MAX_LENGTH,
   OffsetDays: () => OffsetDays,
   Ok: () => Ok,
   PLAN_FEATURES: () => PLAN_FEATURES,
@@ -344,6 +355,8 @@ __export(index_exports, {
   Template: () => Template,
   TemplateCompileRequest: () => TemplateCompileRequest,
   TemplateCreate: () => TemplateCreate,
+  TemplateCreatedData: () => TemplateCreatedData,
+  TemplateDeletedData: () => TemplateDeletedData,
   TemplateDocument: () => TemplateDocument,
   TemplateExportQuery: () => TemplateExportQuery,
   TemplateImport: () => TemplateImport,
@@ -353,6 +366,7 @@ __export(index_exports, {
   TemplateListQuery: () => TemplateListQuery,
   TemplateSummary: () => TemplateSummary,
   TemplateUpdate: () => TemplateUpdate,
+  TemplateUpdatedData: () => TemplateUpdatedData,
   TemplateVersion: () => TemplateVersion,
   TemplateVersionParams: () => TemplateVersionParams,
   TimeOfDay: () => TimeOfDay,
@@ -429,6 +443,7 @@ __export(index_exports, {
   matchRoute: () => matchRoute,
   missingRequiredMergeFields: () => missingRequiredMergeFields,
   nowSeconds: () => nowSeconds,
+  operationsWithAccess: () => operationsWithAccess,
   page: () => page,
   parseExportWarningsHeader: () => parseExportWarningsHeader,
   parseUsageWarningHeader: () => parseUsageWarningHeader,
@@ -566,6 +581,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";
@@ -889,7 +906,12 @@ var Mailing = import_zod5.z.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,
@@ -914,7 +936,13 @@ var MailingContent = {
   name: import_zod5.z.string().max(200).optional(),
   subject: import_zod5.z.string().min(1).max(998),
   preheader: import_zod5.z.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()
 };
@@ -930,7 +958,8 @@ var MailingUpdate = import_zod5.z.object({
   name: import_zod5.z.string().max(200).nullable().optional(),
   subject: MailingContent.subject.optional(),
   preheader: import_zod5.z.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()
@@ -978,6 +1007,8 @@ var Recipient = import_zod5.z.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 = import_zod5.z.object({
   contact_id: Id.optional(),
   external_id: import_zod5.z.string().min(1).max(255).optional(),
@@ -2358,10 +2389,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 = import_zod8.z.string().min(1).max(64);
 var ASSET_POLICIES = ["any", "service_only"];
 var AssetPolicy = import_zod8.z.enum(ASSET_POLICIES);
+var MAX_ALLOWED_ASSET_HOSTS = 20;
+var AssetHost = import_zod8.z.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 = import_zod8.z.string().regex(/^[a-z][a-z0-9_]*$/, "a merge-field name: lowercase letters, digits and underscores, starting with a letter").max(64);
+var MergeDefaultValue = import_zod8.z.union([import_zod8.z.string().max(MAX_MERGE_DEFAULT_LENGTH), import_zod8.z.number().finite(), import_zod8.z.boolean()]);
+var MergeDefaults = import_zod8.z.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 = import_zod8.z.object({
   /** Default language of the hosted unsubscribe page (BCP 47 tag, e.g. "de"). */
   default_locale: import_zod8.z.string().min(2).max(35),
@@ -2371,6 +2437,14 @@ var WorkspaceSettings = import_zod8.z.object({
   tracking_enabled: import_zod8.z.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: import_zod8.z.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.
@@ -2472,6 +2546,7 @@ var AUDIT_ACTIONS = [
   "provider.anomaly_cleared",
   "topic.created",
   "topic.updated",
+  "topic.deleted",
   "template.created",
   "template.updated",
   "template.deleted",
@@ -2539,7 +2614,16 @@ var AUDIT_ACTIONS = [
 var AuditAction = import_zod8.z.enum(AUDIT_ACTIONS);
 var AuditActor = import_zod8.z.discriminatedUnion("type", [
   import_zod8.z.object({ type: import_zod8.z.literal("member"), member_id: Id, subject: import_zod8.z.string().min(1) }),
-  import_zod8.z.object({ type: import_zod8.z.literal("api_key"), api_key_id: Id }),
+  import_zod8.z.object({
+    type: import_zod8.z.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: import_zod8.z.string().min(1).max(ON_BEHALF_OF_MAX_LENGTH).optional()
+  }),
   /** The service itself (the worker, a bounce, the hosted unsubscribe page). */
   import_zod8.z.object({ type: import_zod8.z.literal("system"), reason: import_zod8.z.string().min(1).max(200) })
 ]);
@@ -2867,7 +2951,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 = import_zod12.z.enum(WEBHOOK_EVENT_TYPES);
 var MessageEventBase = import_zod12.z.object({
@@ -3029,6 +3122,15 @@ var AutomationWebhookData = AutomationRunEventBase.extend({
   payload: JsonValue.nullable(),
   fired_at: Timestamp
 });
+var TemplateEventBase = import_zod12.z.object({
+  template_id: Id,
+  name: import_zod12.z.string().min(1).max(200),
+  version: import_zod12.z.number().int().min(1),
+  source: import_zod12.z.enum(["api", "dashboard", "mjml_import"])
+});
+var TemplateCreatedData = TemplateEventBase.extend({ created_at: Timestamp });
+var TemplateUpdatedData = TemplateEventBase.extend({ archived: import_zod12.z.boolean(), updated_at: Timestamp });
+var TemplateDeletedData = TemplateEventBase.extend({ deleted_at: Timestamp });
 var envelope = (type, data) => import_zod12.z.object({
   /** Unique per event: a receiver deduplicates on it (deliveries may repeat). */
   id: Id,
@@ -3056,7 +3158,10 @@ var WebhookEvent = import_zod12.z.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 = import_zod12.z.object({
   id: Id,
@@ -3179,32 +3284,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
 var import_zod13 = require("zod");
 var PLAN_IDS = ["free", "starter", "growth", "design_partner"];
@@ -3715,6 +3794,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",
@@ -4632,6 +4721,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;
@@ -4683,6 +4775,7 @@ function matchRoute(method, pathname) {
   ApiKeyScope,
   Asset,
   AssetContentType,
+  AssetHost,
   AssetImport,
   AssetPolicy,
   AuditAction,
@@ -4832,11 +4925,13 @@ function matchRoute(method, pathname) {
   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,
@@ -4849,6 +4944,9 @@ function matchRoute(method, pathname) {
   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,
@@ -4893,6 +4991,9 @@ function matchRoute(method, pathname) {
   MemberCreate,
   MemberRole,
   MemberUpdate,
+  MergeDefaultValue,
+  MergeDefaults,
+  MergeFieldName,
   Message,
   MessageFailedData,
   MessageListQuery,
@@ -4901,6 +5002,8 @@ function matchRoute(method, pathname) {
   MessageSummary,
   NotifyRecipients,
   NotifyStep,
+  ON_BEHALF_OF_HEADER,
+  ON_BEHALF_OF_MAX_LENGTH,
   OffsetDays,
   Ok,
   PLAN_FEATURES,
@@ -4978,6 +5081,8 @@ function matchRoute(method, pathname) {
   Template,
   TemplateCompileRequest,
   TemplateCreate,
+  TemplateCreatedData,
+  TemplateDeletedData,
   TemplateDocument,
   TemplateExportQuery,
   TemplateImport,
@@ -4987,6 +5092,7 @@ function matchRoute(method, pathname) {
   TemplateListQuery,
   TemplateSummary,
   TemplateUpdate,
+  TemplateUpdatedData,
   TemplateVersion,
   TemplateVersionParams,
   TimeOfDay,
@@ -5063,6 +5169,7 @@ function matchRoute(method, pathname) {
   matchRoute,
   missingRequiredMergeFields,
   nowSeconds,
+  operationsWithAccess,
   page,
   parseExportWarningsHeader,
   parseUsageWarningHeader,