@oxygen-agent/cli 1.1014.1696 → 1.1014.1870

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/README.md +1 -1
  2. package/dist/admin-primary-providers-render.js +7 -2
  3. package/dist/command-families/program.js +4 -0
  4. package/dist/command-families/tables/register-relations.js +3 -2
  5. package/dist/command-manifest.js +14 -2
  6. package/dist/command-support.js +1 -1
  7. package/dist/commands/admin.js +82 -1
  8. package/dist/commands/billing.js +1 -1
  9. package/dist/commands/columns.js +2 -1
  10. package/dist/commands/copilot.js +29 -7
  11. package/dist/commands/domains.js +7 -0
  12. package/dist/commands/email-assets.d.ts +3 -0
  13. package/dist/commands/email-assets.js +78 -0
  14. package/dist/commands/email-templates.d.ts +3 -0
  15. package/dist/commands/email-templates.js +101 -0
  16. package/dist/commands/enrich-column.js +2 -1
  17. package/dist/commands/managed-inboxes.js +26 -1
  18. package/dist/commands/sequences.js +47 -12
  19. package/dist/commands/subscriptions.d.ts +2 -4
  20. package/dist/commands/subscriptions.js +297 -51
  21. package/dist/commands/table-runs.js +2 -1
  22. package/dist/sequence-start-at.d.ts +7 -0
  23. package/dist/sequence-start-at.js +21 -0
  24. package/dist/sequences-brand-kit-command.d.ts +28 -0
  25. package/dist/sequences-brand-kit-command.js +83 -0
  26. package/dist/sequences-content-commands.d.ts +28 -0
  27. package/dist/sequences-content-commands.js +176 -0
  28. package/dist/sequences-newsletter-commands.d.ts +6 -0
  29. package/dist/sequences-newsletter-commands.js +108 -0
  30. package/dist/sequences-test-send-command.d.ts +3 -0
  31. package/dist/sequences-test-send-command.js +47 -0
  32. package/node_modules/@oxygen/formula/dist/evaluate.js +2 -4
  33. package/node_modules/@oxygen/formula/dist/expression.d.ts +7 -5
  34. package/node_modules/@oxygen/formula/dist/expression.js +26 -4
  35. package/node_modules/@oxygen/formula/dist/formula-functions.d.ts +6 -0
  36. package/node_modules/@oxygen/formula/dist/formula-functions.js +55 -0
  37. package/node_modules/@oxygen/shared/dist/billing.d.ts +2 -2
  38. package/node_modules/@oxygen/shared/dist/billing.js +5 -7
  39. package/node_modules/@oxygen/shared/dist/bulk-email-pacing.d.ts +105 -0
  40. package/node_modules/@oxygen/shared/dist/bulk-email-pacing.js +125 -0
  41. package/node_modules/@oxygen/shared/dist/capability-discovery.d.ts +29 -0
  42. package/node_modules/@oxygen/shared/dist/capability-discovery.js +174 -10
  43. package/node_modules/@oxygen/shared/dist/contracts/clay-migration.d.ts +1 -0
  44. package/node_modules/@oxygen/shared/dist/contracts/clay-migration.js +28 -2
  45. package/node_modules/@oxygen/shared/dist/contracts/copilot-attachment-read.d.ts +24 -0
  46. package/node_modules/@oxygen/shared/dist/contracts/copilot-attachment-read.js +7 -0
  47. package/node_modules/@oxygen/shared/dist/contracts/teammates.js +6 -1
  48. package/node_modules/@oxygen/shared/dist/diagnostic-spool.js +90 -14
  49. package/node_modules/@oxygen/shared/dist/email-brand-kit.d.ts +108 -0
  50. package/node_modules/@oxygen/shared/dist/email-brand-kit.js +214 -0
  51. package/node_modules/@oxygen/shared/dist/email-delivery.d.ts +10 -0
  52. package/node_modules/@oxygen/shared/dist/email-delivery.js +14 -0
  53. package/node_modules/@oxygen/shared/dist/email-documents.d.ts +61 -0
  54. package/node_modules/@oxygen/shared/dist/email-documents.js +143 -0
  55. package/node_modules/@oxygen/shared/dist/email-dsn.js +52 -10
  56. package/node_modules/@oxygen/shared/dist/email-html-sanitize.d.ts +23 -0
  57. package/node_modules/@oxygen/shared/dist/email-html-sanitize.js +96 -0
  58. package/node_modules/@oxygen/shared/dist/email-subscriptions.d.ts +63 -1
  59. package/node_modules/@oxygen/shared/dist/email-subscriptions.js +149 -1
  60. package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.d.ts +41 -2
  61. package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.js +50 -1
  62. package/node_modules/@oxygen/shared/dist/external-write-policy.js +5 -1
  63. package/node_modules/@oxygen/shared/dist/group-commit-queue.d.ts +34 -0
  64. package/node_modules/@oxygen/shared/dist/group-commit-queue.js +103 -0
  65. package/node_modules/@oxygen/shared/dist/listed-website-platforms.d.ts +2 -0
  66. package/node_modules/@oxygen/shared/dist/listed-website-platforms.js +26 -0
  67. package/node_modules/@oxygen/shared/dist/newsletter-analytics.d.ts +90 -0
  68. package/node_modules/@oxygen/shared/dist/newsletter-analytics.js +28 -0
  69. package/node_modules/@oxygen/shared/dist/newsletter-test-send.d.ts +20 -0
  70. package/node_modules/@oxygen/shared/dist/newsletter-test-send.js +46 -0
  71. package/node_modules/@oxygen/shared/dist/object-storage.d.ts +11 -0
  72. package/node_modules/@oxygen/shared/dist/object-storage.js +12 -0
  73. package/node_modules/@oxygen/shared/dist/plan-band.d.ts +9 -0
  74. package/node_modules/@oxygen/shared/dist/plan-band.js +17 -0
  75. package/node_modules/@oxygen/shared/dist/plan-capabilities.d.ts +4 -2
  76. package/node_modules/@oxygen/shared/dist/plan-capabilities.js +12 -1
  77. package/node_modules/@oxygen/shared/dist/plan-limits-view.d.ts +2 -0
  78. package/node_modules/@oxygen/shared/dist/plan-limits-view.js +3 -0
  79. package/node_modules/@oxygen/shared/dist/pricing-snapshot.generated.d.ts +5 -0
  80. package/node_modules/@oxygen/shared/dist/pricing-snapshot.generated.js +5 -0
  81. package/node_modules/@oxygen/shared/dist/product-analytics-events.d.ts +29 -0
  82. package/node_modules/@oxygen/shared/dist/product-analytics-events.js +29 -0
  83. package/node_modules/@oxygen/shared/dist/provider-balance-signal.js +7 -0
  84. package/node_modules/@oxygen/shared/dist/sending-domain-faults.d.ts +21 -0
  85. package/node_modules/@oxygen/shared/dist/sending-domain-faults.js +53 -0
  86. package/node_modules/@oxygen/shared/dist/sending-domain-rollout.d.ts +24 -1
  87. package/node_modules/@oxygen/shared/dist/sending-domain-rollout.js +51 -4
  88. package/node_modules/@oxygen/shared/dist/sequence-failures.d.ts +10 -1
  89. package/node_modules/@oxygen/shared/dist/sequence-failures.js +68 -6
  90. package/node_modules/@oxygen/shared/dist/sequence-lifecycle.d.ts +34 -3
  91. package/node_modules/@oxygen/shared/dist/sequence-lifecycle.js +57 -4
  92. package/node_modules/@oxygen/shared/dist/sequence-template.d.ts +17 -0
  93. package/node_modules/@oxygen/shared/dist/sequence-template.js +0 -0
  94. package/node_modules/@oxygen/shared/dist/sequences.d.ts +41 -0
  95. package/node_modules/@oxygen/shared/dist/sequences.js +86 -4
  96. package/node_modules/@oxygen/shared/dist/ses-identity-policy.d.ts +19 -0
  97. package/node_modules/@oxygen/shared/dist/ses-identity-policy.js +54 -0
  98. package/node_modules/@oxygen/shared/dist/skill-play-routing.d.ts +22 -0
  99. package/node_modules/@oxygen/shared/dist/skill-play-routing.js +75 -0
  100. package/node_modules/@oxygen/shared/dist/skill-plays.generated.d.ts +5 -0
  101. package/node_modules/@oxygen/shared/dist/skill-plays.generated.js +269 -0
  102. package/node_modules/@oxygen/shared/dist/spend-safety.d.ts +7 -0
  103. package/node_modules/@oxygen/shared/dist/spend-safety.js +7 -0
  104. package/node_modules/@oxygen/shared/dist/table-limits.d.ts +6 -4
  105. package/node_modules/@oxygen/shared/dist/table-limits.js +6 -4
  106. package/node_modules/@oxygen/shared/dist/teammates.js +2 -1
  107. package/node_modules/@oxygen/shared/dist/user-capability-routing.js +15 -1
  108. package/node_modules/@oxygen/shared/dist/version.generated.d.ts +1 -1
  109. package/node_modules/@oxygen/shared/dist/version.generated.js +1 -1
  110. package/node_modules/@oxygen/shared/dist/workspace-event-catalog.js +2 -2
  111. package/node_modules/@oxygen/shared/package.json +5 -0
  112. package/package.json +2 -2
@@ -0,0 +1,143 @@
1
+ /**
2
+ * Email documents: the designed body of a newsletter step (or a reusable
3
+ * template), stored once with append-only revisions (tenant migration 0555)
4
+ * and referenced by a step as `body_document {id, revision}`. This leaf holds
5
+ * the shared vocabulary every surface validates against; storage lives in
6
+ * `@oxygen/tenant-db/email-documents`. Browser-safe: no Node imports.
7
+ */
8
+ import { sanitizeEmailHtml } from "./email-html-sanitize.js";
9
+ /** Gmail clips a message above ~102 KB; the server refuses a revision above this. */
10
+ export const EMAIL_DOCUMENT_MAX_HTML_BYTES = 102_400;
11
+ /** The editor's size meter warns from here. */
12
+ export const EMAIL_DOCUMENT_WARN_HTML_BYTES = 81_920;
13
+ export const EMAIL_DOCUMENT_MAX_TEXT_CHARS = 102_400;
14
+ export const EMAIL_DOCUMENT_MAX_PREVIEW_TEXT_CHARS = 500;
15
+ export const EMAIL_DOCUMENT_MAX_NAME_CHARS = 200;
16
+ /** The editor's JSON tree; generous, but bounded so a revision row stays small. */
17
+ export const EMAIL_DOCUMENT_MAX_EDITOR_JSON_BYTES = 512_000;
18
+ export const EMAIL_DOCUMENT_ROLES = ["step", "template"];
19
+ export const EMAIL_DOCUMENT_KINDS = ["visual", "html"];
20
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
21
+ export function isEmailDocumentId(value) {
22
+ return typeof value === "string" && UUID_RE.test(value);
23
+ }
24
+ /** UTF-8 byte length, the unit Gmail clips on. */
25
+ export function emailHtmlByteLength(html) {
26
+ return new TextEncoder().encode(html).length;
27
+ }
28
+ /** A refused document input: a fixed sentence naming the field (ADR 0023 validation copy). */
29
+ export class EmailDocumentInputError extends Error {
30
+ code;
31
+ field;
32
+ details;
33
+ constructor(code, field, message, details = {}) {
34
+ super(message);
35
+ this.name = "EmailDocumentInputError";
36
+ this.code = code;
37
+ this.field = field;
38
+ this.details = details;
39
+ }
40
+ }
41
+ const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: "\"", apos: "'", nbsp: " ", "#39": "'" };
42
+ /**
43
+ * A readable plain-text part from email HTML, for a revision saved without one.
44
+ * Links keep their target (`label (https://...)`); merge tags pass through.
45
+ */
46
+ export function emailHtmlToPlainText(html) {
47
+ const withoutHidden = html
48
+ .replace(/<(head|style|script|title)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, "")
49
+ .replace(/<!--[\s\S]*?-->/g, "");
50
+ const withLinks = withoutHidden.replace(/<a\b[^>]*?\shref\s*=\s*("([^"]*)"|'([^']*)')[^>]*>([\s\S]*?)<\/a\s*>/gi, (_whole, _raw, dq, sq, label) => {
51
+ const href = (dq ?? sq ?? "").trim();
52
+ const text = label.replace(/<[^>]+>/g, "").trim();
53
+ if (!href || href === "#" || href.startsWith("mailto:") && text.includes(href.slice(7)))
54
+ return text;
55
+ return text && text !== href ? `${text} (${href})` : href;
56
+ });
57
+ const text = withLinks
58
+ .replace(/<br\s*\/?>/gi, "\n")
59
+ .replace(/<\/(p|div|h[1-6]|li|tr|table|blockquote|section|article|header|footer)\s*>/gi, "\n\n")
60
+ .replace(/<li\b[^>]*>/gi, "- ")
61
+ .replace(/<[^>]+>/g, "")
62
+ .replace(/&(#\d+|#x[0-9a-f]+|[a-z]+);/gi, (entity, name) => {
63
+ const lower = name.toLowerCase();
64
+ if (lower.startsWith("#x"))
65
+ return String.fromCharCode(Number.parseInt(lower.slice(2), 16));
66
+ if (lower.startsWith("#") && lower !== "#39")
67
+ return String.fromCharCode(Number.parseInt(lower.slice(1), 10));
68
+ return ENTITIES[lower] ?? entity;
69
+ });
70
+ return text
71
+ .split("\n")
72
+ .map((line) => line.replace(/[ \t ]+/g, " ").trim())
73
+ .join("\n")
74
+ .replace(/\n{3,}/g, "\n\n")
75
+ .trim();
76
+ }
77
+ /**
78
+ * Validate one revision's content: raw HTML is cleaned of active content,
79
+ * text is derived when absent, and the 100 KB HTML ceiling is enforced on the
80
+ * cleaned bytes. Throws EmailDocumentInputError; never truncates.
81
+ */
82
+ export function normalizeEmailDocumentContent(input) {
83
+ if (typeof input.html !== "string" || !input.html.trim()) {
84
+ throw new EmailDocumentInputError("invalid_email_document", "html", "html is required and must be a non-empty string.");
85
+ }
86
+ const cleaned = sanitizeEmailHtml(input.html);
87
+ const htmlBytes = emailHtmlByteLength(cleaned.html);
88
+ if (htmlBytes > EMAIL_DOCUMENT_MAX_HTML_BYTES) {
89
+ throw new EmailDocumentInputError("email_document_too_large", "html", `The email's HTML is ${htmlBytes} bytes; the limit is ${EMAIL_DOCUMENT_MAX_HTML_BYTES} bytes (Gmail clips larger emails). Remove content or images embedded as data.`, { html_bytes: htmlBytes, max_html_bytes: EMAIL_DOCUMENT_MAX_HTML_BYTES });
90
+ }
91
+ let text;
92
+ if (input.text === undefined || input.text === null || (typeof input.text === "string" && !input.text.trim())) {
93
+ text = emailHtmlToPlainText(cleaned.html);
94
+ }
95
+ else if (typeof input.text !== "string") {
96
+ throw new EmailDocumentInputError("invalid_email_document", "text", "text must be a string.");
97
+ }
98
+ else {
99
+ text = input.text;
100
+ }
101
+ if (text.length > EMAIL_DOCUMENT_MAX_TEXT_CHARS) {
102
+ throw new EmailDocumentInputError("email_document_too_large", "text", `The plain-text part is longer than ${EMAIL_DOCUMENT_MAX_TEXT_CHARS} characters.`, { max_text_chars: EMAIL_DOCUMENT_MAX_TEXT_CHARS });
103
+ }
104
+ let previewText = null;
105
+ if (input.previewText !== undefined && input.previewText !== null) {
106
+ if (typeof input.previewText !== "string") {
107
+ throw new EmailDocumentInputError("invalid_email_document", "preview_text", "preview_text must be a string.");
108
+ }
109
+ if (input.previewText.length > EMAIL_DOCUMENT_MAX_PREVIEW_TEXT_CHARS) {
110
+ throw new EmailDocumentInputError("invalid_email_document", "preview_text", `preview_text must be at most ${EMAIL_DOCUMENT_MAX_PREVIEW_TEXT_CHARS} characters.`);
111
+ }
112
+ previewText = input.previewText.trim() ? input.previewText : null;
113
+ }
114
+ let editorJson = null;
115
+ if (input.editorJson !== undefined && input.editorJson !== null) {
116
+ if (typeof input.editorJson !== "object") {
117
+ throw new EmailDocumentInputError("invalid_email_document", "editor_json", "editor_json must be a JSON object.");
118
+ }
119
+ if (emailHtmlByteLength(JSON.stringify(input.editorJson)) > EMAIL_DOCUMENT_MAX_EDITOR_JSON_BYTES) {
120
+ throw new EmailDocumentInputError("email_document_too_large", "editor_json", `editor_json is larger than ${EMAIL_DOCUMENT_MAX_EDITOR_JSON_BYTES} bytes.`);
121
+ }
122
+ editorJson = input.editorJson;
123
+ }
124
+ return { html: cleaned.html, text, previewText, editorJson, htmlBytes, sanitized: cleaned.sanitized, removed: cleaned.removed };
125
+ }
126
+ export function normalizeEmailDocumentName(value, fallback) {
127
+ if (value === undefined || value === null)
128
+ return fallback;
129
+ if (typeof value !== "string" || !value.trim()) {
130
+ throw new EmailDocumentInputError("invalid_email_document", "name", "name must be a non-empty string.");
131
+ }
132
+ const name = value.trim();
133
+ if (name.length > EMAIL_DOCUMENT_MAX_NAME_CHARS) {
134
+ throw new EmailDocumentInputError("invalid_email_document", "name", `name must be at most ${EMAIL_DOCUMENT_MAX_NAME_CHARS} characters.`);
135
+ }
136
+ return name;
137
+ }
138
+ export function isEmailDocumentRole(value) {
139
+ return typeof value === "string" && EMAIL_DOCUMENT_ROLES.includes(value);
140
+ }
141
+ export function isEmailDocumentKind(value) {
142
+ return typeof value === "string" && EMAIL_DOCUMENT_KINDS.includes(value);
143
+ }
@@ -145,9 +145,21 @@ const REPUTATION_BLOCK = /\b5\.7\.\d{1,3}\b/;
145
145
  const MAILBOX_FULL_CODE = /\b[45]\.2\.2\b/;
146
146
  // 5.1.0 is a generic address-status failure, not proof the recipient is invalid.
147
147
  const NO_SUCH_USER_CODE = /\b5\.1\.(?:[123]|10)\b/;
148
+ // Exchange Online: "550 5.4.310 DNS domain <d> does not exist [Message=InfoDomainNonexistent]".
149
+ const NO_SUCH_DOMAIN_CODE = /^5\.4\.310$/;
150
+ // Generic or routing statuses whose own prose may still prove an invalid destination.
151
+ const GENERIC_ADDRESS_CODE = /^5\.(?:0\.\d{1,3}|1\.0)$/;
152
+ const ROUTING_CODE = /^5\.4\.\d{1,3}$/;
148
153
  const TRANSIENT_CODE = /(\b4\.\d{1,3}\.\d{1,3}\b|\b4\d{2}\b)/;
149
- const MAILBOX_FULL_TEXT = /(mailbox (?:is )?full|over quota|quota exceeded|insufficient storage)/i;
150
- const NO_SUCH_USER_TEXT = /((?:address|account|recipient|user|mailbox|domain)[^\n.]{0,100}(?:does ?n[o']?t exist|could(?: not|n['’]t) be found)|nosuchuser|no such (?:user|recipient|mailbox)|(?:user|recipient) unknown|unknown (?:user|recipient)|(?:recipient |email )?address not found|recipient (?:address )?not found|invalid (?:recipient|email address)|no (?:valid )?MX(?: (?:record|records))?\b|\bNXDOMAIN\b)/i;
154
+ const MAILBOX_FULL_TEXT = /(mailbox (?:is )?full|mailbox for user is full|over quota|quota exceeded|insufficient storage)/i;
155
+ // A domain contains dots, so the gap may cross "." but not a sentence end.
156
+ const NAMED_GAP = String.raw `(?:[^\n.]|\.(?=\S)){0,100}`;
157
+ const INVALID_RECIPIENT_TEXT = new RegExp(String.raw `((?:address|account|recipient|user|mailbox)${NAMED_GAP}(?:does ?n[o']?t exist|could(?: not|n['’]t) be found)|nosuchuser|no such (?:user|recipient|mailbox)|(?:user|recipient) unknown|unknown (?:user|recipient)|(?:recipient |email )?address not found|recipient (?:address )?not found|RecipientNotFound|RecipNotFound|mailbox not found|no mailbox (?:here )?by that name|invalid (?:recipient|mailbox|email address)|unrouteable address)`, "i");
158
+ const INVALID_DOMAIN_TEXT = new RegExp(String.raw `(domain${NAMED_GAP}(?:does ?n[o']?t exist|could(?: not|n['’]t) be found)|domain name not found|host or domain name not found|InfoDomainNonexistent|no (?:valid )?MX(?: (?:record|records))?\b|\bNXDOMAIN\b)`, "i");
159
+ const NO_SUCH_USER_TEXT = new RegExp(`${INVALID_RECIPIENT_TEXT.source}|${INVALID_DOMAIN_TEXT.source}`, "i");
160
+ // Exchange/Outlook headline: "<local> wasn't found at <domain>." It is the
161
+ // receiving directory's verdict only when it names the report's own recipient.
162
+ const EXCHANGE_RECIPIENT_NOT_FOUND = /(?:^|[\s>])([^\s@<>"'()]+)\s+wasn['’]t found at\s+([a-z0-9-]+(?:\.[a-z0-9-]+)+)/gi;
151
163
  const PROVIDER_REJECTED_TEXT = /(message rejected|has been blocked|\bblocked\b|\bbanned\b|\bspam\b|local policy violation|unsolicited|reputation)/i;
152
164
  const TRANSIENT_TEXT = /(temporar|will retry|try again later|rate ?limit|throttl)/i;
153
165
  // Greedy address capture: the character class already stops at whitespace and
@@ -178,24 +190,53 @@ function readProvider(from, haystack) {
178
190
  return "microsoft";
179
191
  return "unknown";
180
192
  }
181
- function readKind(subject, haystack, hasBody, enhancedCode) {
193
+ function namesExchangeRecipientNotFound(haystack, recipient) {
194
+ if (!recipient)
195
+ return false;
196
+ for (const match of haystack.matchAll(EXCHANGE_RECIPIENT_NOT_FOUND)) {
197
+ if (`${match[1]}@${match[2]}`.toLowerCase() === recipient)
198
+ return true;
199
+ }
200
+ return false;
201
+ }
202
+ function readKind(subject, haystack, hasBody, enhancedCode, recipient) {
182
203
  // Order is load-bearing. A Google "(Delay)" report can quote block-sounding
183
204
  // prose while the message is still queued, so the transient marker wins first;
184
205
  // an explicit enhanced code then beats keyword matching, because "blocked" and
185
206
  // "spam" appear in boilerplate that a 5.1.1 no-such-user report also carries.
186
207
  if (/\(delay\)/i.test(subject))
187
208
  return "delayed";
209
+ const exchangeNotFound = namesExchangeRecipientNotFound(haystack, recipient);
188
210
  if (enhancedCode) {
211
+ // Spam, policy and quota statuses stay stop-only whatever the prose says.
189
212
  if (REPUTATION_BLOCK.test(enhancedCode))
190
213
  return "provider_rejected";
191
214
  if (MAILBOX_FULL_CODE.test(enhancedCode))
192
215
  return "mailbox_full";
193
- if (NO_SUCH_USER_CODE.test(enhancedCode))
194
- return "no_such_user";
216
+ if (NO_SUCH_USER_CODE.test(enhancedCode)) {
217
+ // Postfix address verification wraps a full mailbox as "550 5.1.1
218
+ // undeliverable address: ... said: 552 5.2.2 Quota exceeded".
219
+ return MAILBOX_FULL_CODE.test(haystack) || MAILBOX_FULL_TEXT.test(haystack) ? "mailbox_full" : "no_such_user";
220
+ }
195
221
  if (enhancedCode.startsWith("4."))
196
222
  return "delayed";
197
- // An explicit generic/routing failure is not address-nonexistence evidence,
198
- // even when the surrounding help text suggests checking the address.
223
+ if (NO_SUCH_DOMAIN_CODE.test(enhancedCode))
224
+ return "no_such_user";
225
+ // SignalFisher, 2026-10-22: Exchange's "554 5.4.14 Hop count exceeded" for
226
+ // malpertuis@intracen.org carried "malpertuis wasn't found at intracen.org";
227
+ // the receiving directory does not know the address. A routing status needs
228
+ // that recipient-bound headline or nonexistent-domain prose, never help text.
229
+ if (ROUTING_CODE.test(enhancedCode) && (exchangeNotFound || INVALID_DOMAIN_TEXT.test(haystack)))
230
+ return "no_such_user";
231
+ if (GENERIC_ADDRESS_CODE.test(enhancedCode)) {
232
+ // Only the diagnostic line itself counts ("550 5.0.0 <x>: User unknown");
233
+ // Outlook's "Recipient Unknown" heading is a template, not a verdict.
234
+ const diagnostic = haystack.split("\n").filter(line => line.includes(enhancedCode)).join("\n");
235
+ if (!PROVIDER_REJECTED_TEXT.test(diagnostic) && (exchangeNotFound || NO_SUCH_USER_TEXT.test(diagnostic)))
236
+ return "no_such_user";
237
+ }
238
+ // Any other explicit failure is not address-nonexistence evidence, even
239
+ // when the surrounding help text suggests checking the address.
199
240
  return "other";
200
241
  }
201
242
  if (MAILBOX_FULL_TEXT.test(haystack))
@@ -204,7 +245,7 @@ function readKind(subject, haystack, hasBody, enhancedCode) {
204
245
  return "provider_rejected";
205
246
  if (ENHANCED_CODE.test(haystack))
206
247
  return "other";
207
- if (NO_SUCH_USER_TEXT.test(haystack))
248
+ if (exchangeNotFound || NO_SUCH_USER_TEXT.test(haystack))
208
249
  return "no_such_user";
209
250
  if (TRANSIENT_CODE.test(haystack) || TRANSIENT_TEXT.test(haystack))
210
251
  return "delayed";
@@ -228,10 +269,11 @@ export function classifyDeliveryStatusNotification(input) {
228
269
  const haystack = `${subject}\n${body}`;
229
270
  const enhancedCode = readEnhancedStatusCode(haystack);
230
271
  const smtpCode = enhancedCode ?? (ENHANCED_CODE.test(haystack) ? null : SMTP_REPLY_CODE.exec(haystack)?.[1] ?? null);
272
+ const recipient = readRecipient(haystack);
231
273
  return {
232
- kind: readKind(subject, haystack, body.trim().length > 0, enhancedCode),
274
+ kind: readKind(subject, haystack, body.trim().length > 0, enhancedCode, recipient),
233
275
  provider: readProvider(from, haystack),
234
- recipient: readRecipient(haystack),
276
+ recipient,
235
277
  smtpCode,
236
278
  };
237
279
  }
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Clean raw HTML a customer saves as an email document. Email clients never run
3
+ * scripts, but the same HTML is previewed in the web app and forwarded by
4
+ * recipients, so active content is removed on save rather than trusted to every
5
+ * reader: `<script>` (and other embedding elements), inline `on*` event
6
+ * handlers, and `javascript:` / `vbscript:` / `data:text/html` URLs in link and
7
+ * source attributes. Styles, tables, images and merge tags are kept as written.
8
+ *
9
+ * Browser-safe and dependency-free. This is a save-time cleanup, not the
10
+ * preview boundary: the web preview still renders inside a sandboxed iframe.
11
+ */
12
+ export type EmailHtmlSanitizeResult = {
13
+ html: string;
14
+ /** What was removed, for the save response (`sanitized` is true when anything was). */
15
+ removed: {
16
+ elements: number;
17
+ handlers: number;
18
+ urls: number;
19
+ };
20
+ sanitized: boolean;
21
+ };
22
+ export declare function isUnsafeEmailUrl(value: string): boolean;
23
+ export declare function sanitizeEmailHtml(input: string): EmailHtmlSanitizeResult;
@@ -0,0 +1,96 @@
1
+ /**
2
+ * Clean raw HTML a customer saves as an email document. Email clients never run
3
+ * scripts, but the same HTML is previewed in the web app and forwarded by
4
+ * recipients, so active content is removed on save rather than trusted to every
5
+ * reader: `<script>` (and other embedding elements), inline `on*` event
6
+ * handlers, and `javascript:` / `vbscript:` / `data:text/html` URLs in link and
7
+ * source attributes. Styles, tables, images and merge tags are kept as written.
8
+ *
9
+ * Browser-safe and dependency-free. This is a save-time cleanup, not the
10
+ * preview boundary: the web preview still renders inside a sandboxed iframe.
11
+ */
12
+ const ACTIVE_ELEMENTS = ["script", "iframe", "object", "embed", "applet", "frame", "frameset", "base"];
13
+ const URL_ATTRIBUTES = ["href", "src", "action", "formaction", "background", "poster", "xlink:href", "srcset", "lowsrc", "dynsrc"];
14
+ /** Decode the entity tricks used to hide a scheme (`&#106;avascript:`, `java&#x09;script:`). */
15
+ function decodeForSchemeCheck(value) {
16
+ return value
17
+ .replace(/&#x([0-9a-f]+);?/gi, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
18
+ .replace(/&#(\d+);?/g, (_, dec) => String.fromCharCode(Number.parseInt(dec, 10)))
19
+ .replace(/&(tab|newline);/gi, "")
20
+ .replace(/&colon;/gi, ":")
21
+ // Browsers ignore control characters and whitespace inside a scheme.
22
+ // eslint-disable-next-line no-control-regex
23
+ .replace(/[\u0000- \u007f-\u009f]+/g, "")
24
+ .toLowerCase();
25
+ }
26
+ export function isUnsafeEmailUrl(value) {
27
+ const decoded = decodeForSchemeCheck(value);
28
+ return decoded.startsWith("javascript:") || decoded.startsWith("vbscript:") || decoded.startsWith("data:text/html")
29
+ || decoded.startsWith("data:application/xhtml") || decoded.startsWith("data:image/svg+xml");
30
+ }
31
+ // One attribute: a name, then an optional value. `/` separates attributes the way
32
+ // browsers read `<img/onerror=...>`.
33
+ const ATTRIBUTE = /([^\s"'>\/=]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s"'>]+))?/g;
34
+ function unquote(value) {
35
+ return (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")) ? value.slice(1, -1) : value;
36
+ }
37
+ /** The cleaned attribute string, or null when nothing in it needed cleaning. */
38
+ function rewriteAttributes(attrs, removed) {
39
+ let changed = false;
40
+ const kept = [];
41
+ for (const match of attrs.matchAll(ATTRIBUTE)) {
42
+ const name = match[1] ?? "";
43
+ const lower = name.toLowerCase();
44
+ let value = match[2];
45
+ if (lower.startsWith("on")) {
46
+ removed.handlers += 1;
47
+ changed = true;
48
+ continue;
49
+ }
50
+ if (value !== undefined && URL_ATTRIBUTES.includes(lower) && isUnsafeEmailUrl(unquote(value))) {
51
+ removed.urls += 1;
52
+ changed = true;
53
+ value = '"#"';
54
+ }
55
+ else if (value !== undefined && lower === "style") {
56
+ // A style URL can carry the same schemes (`background:url(javascript:...)`).
57
+ const cleaned = value.replace(/url\(\s*(["']?)([^"')]*)\1\s*\)/gi, (whole, _q, url) => {
58
+ if (!isUnsafeEmailUrl(url))
59
+ return whole;
60
+ removed.urls += 1;
61
+ changed = true;
62
+ return "none";
63
+ });
64
+ value = cleaned;
65
+ }
66
+ kept.push(value === undefined ? name : `${name}=${value}`);
67
+ }
68
+ if (!changed)
69
+ return null;
70
+ const selfClosing = /\/\s*$/.test(attrs);
71
+ return `${kept.length > 0 ? ` ${kept.join(" ")}` : ""}${selfClosing ? " /" : ""}`;
72
+ }
73
+ export function sanitizeEmailHtml(input) {
74
+ const removed = { elements: 0, handlers: 0, urls: 0 };
75
+ let html = input;
76
+ for (const element of ACTIVE_ELEMENTS) {
77
+ const paired = new RegExp(`<${element}\\b[^>]*>[\\s\\S]*?<\\/${element}\\s*>`, "gi");
78
+ const single = new RegExp(`<\\/?${element}\\b[^>]*>`, "gi");
79
+ html = html.replace(paired, () => {
80
+ removed.elements += 1;
81
+ return "";
82
+ });
83
+ html = html.replace(single, () => {
84
+ removed.elements += 1;
85
+ return "";
86
+ });
87
+ }
88
+ // Attributes are rewritten only inside tags (quoted values may hold `>`), so prose
89
+ // that mentions "onclick=" survives and an untouched tag keeps its exact bytes.
90
+ html = html.replace(/<([a-z][a-z0-9:-]*)((?:"[^"]*"|'[^']*'|[^'">])*)>/gi, (match, tag, attrs) => {
91
+ const rewritten = rewriteAttributes(attrs, removed);
92
+ return rewritten === null ? match : `<${tag}${rewritten}>`;
93
+ });
94
+ const sanitized = removed.elements + removed.handlers + removed.urls > 0;
95
+ return { html, removed, sanitized };
96
+ }
@@ -8,8 +8,26 @@
8
8
  * Sequences only send to `subscribed` addresses on their own list, on top of
9
9
  * do-not-contact. Pure and browser-safe.
10
10
  */
11
- export declare const EMAIL_SUBSCRIPTION_LIST_KINDS: readonly ["marketing", "product_updates", "onboarding"];
11
+ export declare const EMAIL_SUBSCRIPTION_LIST_KINDS: readonly ["marketing", "product_updates", "onboarding", "topic"];
12
12
  export type EmailSubscriptionListKind = typeof EMAIL_SUBSCRIPTION_LIST_KINDS[number];
13
+ /**
14
+ * Topics: a `topic` list is a narrower subject inside an audience list
15
+ * (`parent_list_id`). A newsletter on a topic mails only the topic's
16
+ * subscribers. `opt_out` topics are joined together with their audience list
17
+ * (the same consent evidence, source `topic_default`); `opt_in` topics only by
18
+ * an explicit choice. Public lists show on the recipient's preference page;
19
+ * private ones only to someone already subscribed to them.
20
+ */
21
+ export declare const EMAIL_SUBSCRIPTION_LIST_VISIBILITIES: readonly ["public", "private"];
22
+ export type EmailSubscriptionListVisibility = typeof EMAIL_SUBSCRIPTION_LIST_VISIBILITIES[number];
23
+ export declare const EMAIL_SUBSCRIPTION_DEFAULTS: readonly ["opt_in", "opt_out"];
24
+ export type EmailSubscriptionDefault = typeof EMAIL_SUBSCRIPTION_DEFAULTS[number];
25
+ /** The consent source of a topic subscription made by joining its audience list. */
26
+ export declare const TOPIC_DEFAULT_SOURCE = "topic_default";
27
+ /** The consent source of a change the recipient made on the hosted preference page. */
28
+ export declare const PREFERENCE_CENTER_SOURCE = "preference_center";
29
+ export declare function isEmailSubscriptionListVisibility(value: unknown): value is EmailSubscriptionListVisibility;
30
+ export declare function isEmailSubscriptionDefault(value: unknown): value is EmailSubscriptionDefault;
13
31
  export declare const EMAIL_SUBSCRIPTION_STATUSES: readonly ["subscribed", "unsubscribed", "pending", "cleaned"];
14
32
  export type EmailSubscriptionStatus = typeof EMAIL_SUBSCRIPTION_STATUSES[number];
15
33
  /** Append-only consent event kinds. Status changes plus the provider facts that cause them. */
@@ -48,3 +66,47 @@ export type EmailConsentEvidence = {
48
66
  export declare function parseEmailConsentEvidence(value: unknown, options: {
49
67
  requireForSubscribe: boolean;
50
68
  }): EmailConsentEvidence;
69
+ /**
70
+ * Contacts of a list: one subscription read together with the Records person it
71
+ * names (`email_subscriptions.person_id`, a People record). Records owns the
72
+ * person (name and the workspace's own People fields, the contact
73
+ * "properties"); the list owns status and consent.
74
+ */
75
+ export declare const EMAIL_CONTACT_PROPERTY_TYPES: readonly ["string", "number"];
76
+ export type EmailContactPropertyType = typeof EMAIL_CONTACT_PROPERTY_TYPES[number];
77
+ /** Most contacts one list page returns. */
78
+ export declare const EMAIL_CONTACTS_PAGE_LIMIT = 200;
79
+ /**
80
+ * Most import entries per call that carry a name or properties: each one is a
81
+ * Records write (create or match the person by email), so these batches are
82
+ * smaller than an address-only import. The CLI and web split larger files.
83
+ */
84
+ export declare const EMAIL_CONTACT_IMPORT_WITH_FIELDS_LIMIT = 1000;
85
+ export declare function isEmailContactPropertyType(value: unknown): value is EmailContactPropertyType;
86
+ /** One contact an import sends: the address, and what goes to its People record. */
87
+ export type EmailContactImportRow = {
88
+ email: string;
89
+ person_id?: string;
90
+ first_name?: string;
91
+ last_name?: string;
92
+ properties?: Record<string, string>;
93
+ };
94
+ /** Parse CSV text into rows of cells, honouring quoted fields ("" escapes, commas and newlines inside quotes). */
95
+ export declare function parseCsvCells(text: string): string[][];
96
+ /**
97
+ * Contacts from a CSV with an email column (the shape `subscriptions export`
98
+ * writes): first_name and last_name go to the person, every other non-reserved
99
+ * column is a candidate property, named in `propertyColumns` so a caller can
100
+ * keep only the workspace's real properties.
101
+ */
102
+ export declare function parseContactsCsv(text: string): {
103
+ entries: EmailContactImportRow[];
104
+ propertyColumns: string[];
105
+ };
106
+ /** Keep only properties the workspace has; report the columns dropped. */
107
+ export declare function keepContactProperties(entries: EmailContactImportRow[], known: ReadonlySet<string>): {
108
+ entries: EmailContactImportRow[];
109
+ ignored: string[];
110
+ };
111
+ /** Split an import into calls the import route accepts (smaller batches once any entry carries a name or properties). */
112
+ export declare function chunkContactImport<T extends EmailContactImportRow>(entries: T[]): T[][];
@@ -8,7 +8,27 @@
8
8
  * Sequences only send to `subscribed` addresses on their own list, on top of
9
9
  * do-not-contact. Pure and browser-safe.
10
10
  */
11
- export const EMAIL_SUBSCRIPTION_LIST_KINDS = ["marketing", "product_updates", "onboarding"];
11
+ export const EMAIL_SUBSCRIPTION_LIST_KINDS = ["marketing", "product_updates", "onboarding", "topic"];
12
+ /**
13
+ * Topics: a `topic` list is a narrower subject inside an audience list
14
+ * (`parent_list_id`). A newsletter on a topic mails only the topic's
15
+ * subscribers. `opt_out` topics are joined together with their audience list
16
+ * (the same consent evidence, source `topic_default`); `opt_in` topics only by
17
+ * an explicit choice. Public lists show on the recipient's preference page;
18
+ * private ones only to someone already subscribed to them.
19
+ */
20
+ export const EMAIL_SUBSCRIPTION_LIST_VISIBILITIES = ["public", "private"];
21
+ export const EMAIL_SUBSCRIPTION_DEFAULTS = ["opt_in", "opt_out"];
22
+ /** The consent source of a topic subscription made by joining its audience list. */
23
+ export const TOPIC_DEFAULT_SOURCE = "topic_default";
24
+ /** The consent source of a change the recipient made on the hosted preference page. */
25
+ export const PREFERENCE_CENTER_SOURCE = "preference_center";
26
+ export function isEmailSubscriptionListVisibility(value) {
27
+ return typeof value === "string" && EMAIL_SUBSCRIPTION_LIST_VISIBILITIES.includes(value);
28
+ }
29
+ export function isEmailSubscriptionDefault(value) {
30
+ return typeof value === "string" && EMAIL_SUBSCRIPTION_DEFAULTS.includes(value);
31
+ }
12
32
  export const EMAIL_SUBSCRIPTION_STATUSES = ["subscribed", "unsubscribed", "pending", "cleaned"];
13
33
  /** Append-only consent event kinds. Status changes plus the provider facts that cause them. */
14
34
  export const EMAIL_SUBSCRIPTION_EVENT_TYPES = [
@@ -78,3 +98,131 @@ export function parseEmailConsentEvidence(value, options) {
78
98
  }
79
99
  return evidence;
80
100
  }
101
+ /**
102
+ * Contacts of a list: one subscription read together with the Records person it
103
+ * names (`email_subscriptions.person_id`, a People record). Records owns the
104
+ * person (name and the workspace's own People fields, the contact
105
+ * "properties"); the list owns status and consent.
106
+ */
107
+ export const EMAIL_CONTACT_PROPERTY_TYPES = ["string", "number"];
108
+ /** Most contacts one list page returns. */
109
+ export const EMAIL_CONTACTS_PAGE_LIMIT = 200;
110
+ /**
111
+ * Most import entries per call that carry a name or properties: each one is a
112
+ * Records write (create or match the person by email), so these batches are
113
+ * smaller than an address-only import. The CLI and web split larger files.
114
+ */
115
+ export const EMAIL_CONTACT_IMPORT_WITH_FIELDS_LIMIT = 1000;
116
+ export function isEmailContactPropertyType(value) {
117
+ return typeof value === "string" && EMAIL_CONTACT_PROPERTY_TYPES.includes(value);
118
+ }
119
+ /** Header names an import reads as the contact itself (or as export bookkeeping), never as a property. */
120
+ const CONTACT_CSV_RESERVED = new Set([
121
+ "email", "email_address", "e-mail", "person_id", "first_name", "last_name", "full_name",
122
+ "status", "source", "subscribed_at", "unsubscribed_at", "consent_at", "consent_source", "consent_basis",
123
+ "consent_notice_version", "consent_form_url",
124
+ ]);
125
+ /** Parse CSV text into rows of cells, honouring quoted fields ("" escapes, commas and newlines inside quotes). */
126
+ export function parseCsvCells(text) {
127
+ const rows = [];
128
+ let row = [];
129
+ let cell = "";
130
+ let quoted = false;
131
+ const input = text.replace(/^/, "");
132
+ for (let index = 0; index < input.length; index += 1) {
133
+ const char = input[index];
134
+ if (quoted) {
135
+ if (char === "\"" && input[index + 1] === "\"") {
136
+ cell += "\"";
137
+ index += 1;
138
+ }
139
+ else if (char === "\"")
140
+ quoted = false;
141
+ else
142
+ cell += char;
143
+ }
144
+ else if (char === "\"")
145
+ quoted = true;
146
+ else if (char === ",") {
147
+ row.push(cell.trim());
148
+ cell = "";
149
+ }
150
+ else if (char === "\n" || char === "\r") {
151
+ if (char === "\r" && input[index + 1] === "\n")
152
+ index += 1;
153
+ row.push(cell.trim());
154
+ cell = "";
155
+ if (row.some((value) => value !== ""))
156
+ rows.push(row);
157
+ row = [];
158
+ }
159
+ else
160
+ cell += char;
161
+ }
162
+ row.push(cell.trim());
163
+ if (row.some((value) => value !== ""))
164
+ rows.push(row);
165
+ return rows;
166
+ }
167
+ /**
168
+ * Contacts from a CSV with an email column (the shape `subscriptions export`
169
+ * writes): first_name and last_name go to the person, every other non-reserved
170
+ * column is a candidate property, named in `propertyColumns` so a caller can
171
+ * keep only the workspace's real properties.
172
+ */
173
+ export function parseContactsCsv(text) {
174
+ const [headerRow = [], ...body] = parseCsvCells(text);
175
+ const header = headerRow.map((cell) => cell.toLowerCase());
176
+ const emailIndex = header.findIndex((cell) => cell === "email" || cell === "email_address" || cell === "e-mail");
177
+ if (emailIndex < 0) {
178
+ throw new EmailSubscriptionInputError("invalid_request", "file", "The CSV needs an email column in its header row.");
179
+ }
180
+ const at = (name) => header.indexOf(name);
181
+ const personIndex = at("person_id");
182
+ const firstIndex = at("first_name");
183
+ const lastIndex = at("last_name");
184
+ const propertyColumns = header.flatMap((cell, index) => (cell && !CONTACT_CSV_RESERVED.has(cell) ? [{ key: cell, index }] : []));
185
+ const entries = body.map((cells) => {
186
+ const properties = Object.fromEntries(propertyColumns.flatMap(({ key, index }) => (cells[index] ? [[key, cells[index]]] : [])));
187
+ const read = (index) => (index >= 0 && cells[index] ? cells[index] : undefined);
188
+ const personId = read(personIndex);
189
+ const firstName = read(firstIndex);
190
+ const lastName = read(lastIndex);
191
+ return {
192
+ email: cells[emailIndex] ?? "",
193
+ ...(personId ? { person_id: personId } : {}),
194
+ ...(firstName ? { first_name: firstName } : {}),
195
+ ...(lastName ? { last_name: lastName } : {}),
196
+ ...(Object.keys(properties).length > 0 ? { properties } : {}),
197
+ };
198
+ });
199
+ return { entries, propertyColumns: propertyColumns.map((column) => column.key) };
200
+ }
201
+ /** Keep only properties the workspace has; report the columns dropped. */
202
+ export function keepContactProperties(entries, known) {
203
+ const columns = new Set(entries.flatMap((entry) => Object.keys(entry.properties ?? {})));
204
+ const ignored = [...columns].filter((column) => !known.has(column)).sort();
205
+ if (ignored.length === 0)
206
+ return { entries, ignored };
207
+ return {
208
+ ignored,
209
+ entries: entries.map((entry) => {
210
+ if (!entry.properties)
211
+ return entry;
212
+ const { properties, ...rest } = entry;
213
+ const kept = Object.fromEntries(Object.entries(properties).filter(([key]) => known.has(key)));
214
+ return Object.keys(kept).length > 0 ? { ...rest, properties: kept } : rest;
215
+ }),
216
+ };
217
+ }
218
+ function importRowHasFields(entry) {
219
+ return Boolean(entry.first_name || entry.last_name || (entry.properties && Object.keys(entry.properties).length > 0));
220
+ }
221
+ /** Split an import into calls the import route accepts (smaller batches once any entry carries a name or properties). */
222
+ export function chunkContactImport(entries) {
223
+ const size = entries.some(importRowHasFields) ? EMAIL_CONTACT_IMPORT_WITH_FIELDS_LIMIT : EMAIL_SUBSCRIPTION_IMPORT_LIMIT;
224
+ const chunks = [];
225
+ for (let index = 0; index < entries.length; index += size)
226
+ chunks.push(entries.slice(index, index + size));
227
+ return chunks.length > 0 ? chunks : [[]];
228
+ }