@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
@@ -55,8 +55,11 @@ export type UnsubscribeTokenPayloadV2 = {
55
55
  email: string;
56
56
  /** Subscription list id the recipient leaves. */
57
57
  lst: string;
58
- /** `list` leaves only `lst`; `all` leaves every list and suppresses the address. */
59
- scope: "list" | "all";
58
+ /**
59
+ * `list` leaves only `lst`; `all` leaves every list and suppresses the
60
+ * address; `test` (a newsletter test send) changes nothing and says so.
61
+ */
62
+ scope: "list" | "all" | "test";
60
63
  seq?: string;
61
64
  enr?: string;
62
65
  /** Sending-domain account id, for provenance. */
@@ -71,6 +74,42 @@ export declare function signUnsubscribeTokenV2(payload: UnsubscribeTokenPayloadV
71
74
  * v1 callers keep `verifyUnsubscribeToken`, whose contract is unchanged.
72
75
  */
73
76
  export declare function verifyAnyUnsubscribeToken(token: string, secret: string): AnyUnsubscribeTokenPayload | null;
77
+ /**
78
+ * v2 `preferences`: the link to the hosted preference page of bulk mail
79
+ * (`{{preferences_url}}`). Same wire format and secret as the unsubscribe
80
+ * tokens, but a separate scope that `verifyAnyUnsubscribeToken` refuses, so a
81
+ * preferences link can never perform a one-click unsubscribe. `test` marks the
82
+ * link of a newsletter test send: the page says so and changes nothing.
83
+ */
84
+ export type PreferencesTokenPayload = {
85
+ v: 2;
86
+ org: string;
87
+ email: string;
88
+ /** The list the email was sent from; the page shows every list the address may manage. */
89
+ lst: string;
90
+ scope: "preferences";
91
+ test?: true;
92
+ seq?: string;
93
+ sd?: string;
94
+ iat: number;
95
+ };
96
+ /** A preferences link stops opening the page a year after the email that carried it. */
97
+ export declare const PREFERENCES_TOKEN_MAX_AGE_MS: number;
98
+ export declare function signPreferencesToken(payload: PreferencesTokenPayload, secret: string): string;
99
+ /**
100
+ * Verify a preferences token: signature, shape and age. Returns null for any
101
+ * problem, including an unsubscribe token (wrong scope) and a link older than
102
+ * PREFERENCES_TOKEN_MAX_AGE_MS; `expired` tells the page which copy to show.
103
+ */
104
+ export declare function verifyPreferencesToken(token: string, secret: string, nowMs?: number): {
105
+ payload: PreferencesTokenPayload;
106
+ expired: false;
107
+ } | {
108
+ payload: null;
109
+ expired: boolean;
110
+ };
111
+ /** The hosted preference page: org id in the path (re-checked against the token), token in `token`. */
112
+ export declare function buildPreferencesUrl(orgId: string, token: string, baseUrl: string): string;
74
113
  /**
75
114
  * The HMAC signing secret for unsubscribe tokens, or null when unset. The send
76
115
  * path treats null as "omit the header" (a send with no one-click link still
@@ -72,7 +72,7 @@ function parseTokenPayloadV2(body) {
72
72
  const lst = typeof candidate.lst === "string" ? candidate.lst.trim() : "";
73
73
  if (!org || !email || !email.includes("@") || !lst)
74
74
  return null;
75
- if (candidate.scope !== "list" && candidate.scope !== "all")
75
+ if (candidate.scope !== "list" && candidate.scope !== "all" && candidate.scope !== "test")
76
76
  return null;
77
77
  return {
78
78
  v: 2,
@@ -96,6 +96,55 @@ export function verifyAnyUnsubscribeToken(token, secret) {
96
96
  return null;
97
97
  return parseTokenPayload(body) ?? parseTokenPayloadV2(body);
98
98
  }
99
+ /** A preferences link stops opening the page a year after the email that carried it. */
100
+ export const PREFERENCES_TOKEN_MAX_AGE_MS = 365 * 24 * 60 * 60 * 1000;
101
+ export function signPreferencesToken(payload, secret) {
102
+ const normalized = { ...payload, email: payload.email.trim().toLowerCase() };
103
+ return signPayload(normalized, secret);
104
+ }
105
+ /**
106
+ * Verify a preferences token: signature, shape and age. Returns null for any
107
+ * problem, including an unsubscribe token (wrong scope) and a link older than
108
+ * PREFERENCES_TOKEN_MAX_AGE_MS; `expired` tells the page which copy to show.
109
+ */
110
+ export function verifyPreferencesToken(token, secret, nowMs = Date.now()) {
111
+ const body = splitAndVerifyToken(token, secret);
112
+ if (body === null)
113
+ return { payload: null, expired: false };
114
+ let parsed;
115
+ try {
116
+ parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
117
+ }
118
+ catch {
119
+ return { payload: null, expired: false };
120
+ }
121
+ if (!parsed || typeof parsed !== "object")
122
+ return { payload: null, expired: false };
123
+ const candidate = parsed;
124
+ const org = typeof candidate.org === "string" ? candidate.org.trim() : "";
125
+ const email = typeof candidate.email === "string" ? candidate.email.trim().toLowerCase() : "";
126
+ const lst = typeof candidate.lst === "string" ? candidate.lst.trim() : "";
127
+ if (candidate.v !== 2 || candidate.scope !== "preferences" || !org || !email.includes("@") || !lst) {
128
+ return { payload: null, expired: false };
129
+ }
130
+ const iat = typeof candidate.iat === "number" && Number.isFinite(candidate.iat) ? candidate.iat : 0;
131
+ if (nowMs - iat > PREFERENCES_TOKEN_MAX_AGE_MS)
132
+ return { payload: null, expired: true };
133
+ return {
134
+ expired: false,
135
+ payload: {
136
+ v: 2, org, email, lst, scope: "preferences",
137
+ ...(candidate.test === true ? { test: true } : {}),
138
+ ...(typeof candidate.seq === "string" && candidate.seq ? { seq: candidate.seq } : {}),
139
+ ...(typeof candidate.sd === "string" && candidate.sd ? { sd: candidate.sd } : {}),
140
+ iat,
141
+ },
142
+ };
143
+ }
144
+ /** The hosted preference page: org id in the path (re-checked against the token), token in `token`. */
145
+ export function buildPreferencesUrl(orgId, token, baseUrl) {
146
+ return `${baseUrl}/email/preferences/${encodeURIComponent(orgId)}?token=${token}`;
147
+ }
99
148
  /**
100
149
  * The HMAC signing secret for unsubscribe tokens, or null when unset. The send
101
150
  * path treats null as "omit the header" (a send with no one-click link still
@@ -64,5 +64,9 @@ export function assertExternalWritesAllowed(action, env = process.env) {
64
64
  if (resolveExternalWritePolicy(env) !== "deny")
65
65
  return;
66
66
  log("warn", "external_writes.denied", { action });
67
- throw new OxygenError(EXTERNAL_WRITES_DENIED_CODE, `External writes are denied in this environment (${EXTERNAL_WRITES_ENV_VAR}=deny), so "${action}" cannot run.`, { details: { action, env_var: EXTERNAL_WRITES_ENV_VAR } });
67
+ throw new OxygenError(EXTERNAL_WRITES_DENIED_CODE, `External writes are denied in this environment (${EXTERNAL_WRITES_ENV_VAR}=deny), so "${action}" cannot run.`,
68
+ // Thrown before any client exists, so it is proof that nothing was sent:
69
+ // the worker settles the item as not_applied and releases its credit hold
70
+ // instead of fencing a retry as an effect of unknown outcome.
71
+ { details: { action, env_var: EXTERNAL_WRITES_ENV_VAR, effect_outcome: "not_applied", provider_call: false } });
68
72
  }
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Group commit for independent, append-only ledger rows.
3
+ *
4
+ * Every caller still awaits its own durable write: its promise settles only
5
+ * after the statement that carried its row acknowledged. Rows that arrive
6
+ * while earlier writes are in flight share the next statement, so an idle
7
+ * process adds one microtask and a loaded one writes up to `maxBatch`
8
+ * rows per round trip instead of one.
9
+ *
10
+ * A failed batch may already be durable (its COMMIT reply can be lost), so
11
+ * both repair writes must be idempotent. A data-class refusal (SQLSTATE 22xxx
12
+ * or 23xxx) names one bad row: the batch is split and its rows are written
13
+ * alone, at most `maxInFlight` at a time, so only the bad row's caller fails.
14
+ * Any other failure is presumed transient and the whole batch is retried once
15
+ * through `retryBatch`; only a data-class refusal of that retry splits it.
16
+ * Above `maxPending` queued rows callers write directly, so a stalled database
17
+ * cannot grow this queue.
18
+ */
19
+ export type GroupCommitWriter<T> = {
20
+ writeOne: (row: T) => Promise<void>;
21
+ writeBatch: (rows: readonly T[]) => Promise<void>;
22
+ /** Idempotent whole-batch retry (e.g. ON CONFLICT DO NOTHING). */
23
+ retryBatch: (rows: readonly T[]) => Promise<void>;
24
+ /** Idempotent single-row write used after a data-class refusal. */
25
+ repairOne: (row: T) => Promise<void>;
26
+ };
27
+ /** SQLSTATE classes 22 (data exception) and 23 (integrity constraint violation). */
28
+ export declare function isRowDataSqlError(error: unknown): boolean;
29
+ export type GroupCommitOptions = {
30
+ maxBatch?: number;
31
+ maxPending?: number;
32
+ maxInFlight?: number;
33
+ };
34
+ export declare function createGroupCommitQueue<T>(writer: GroupCommitWriter<T>, options?: GroupCommitOptions): (row: T) => Promise<void>;
@@ -0,0 +1,103 @@
1
+ import { sqlErrorFields } from "./sql-error.js";
2
+ /** SQLSTATE classes 22 (data exception) and 23 (integrity constraint violation). */
3
+ export function isRowDataSqlError(error) {
4
+ const code = sqlErrorFields(error).sql_error_pg_code;
5
+ return typeof code === "string" && /^2[23]/.test(code);
6
+ }
7
+ export function createGroupCommitQueue(writer, options = {}) {
8
+ const maxBatch = options.maxBatch ?? 64;
9
+ const maxPending = options.maxPending ?? 1024;
10
+ const maxInFlight = options.maxInFlight ?? 2;
11
+ let queue = [];
12
+ let pending = 0;
13
+ let inFlight = 0;
14
+ let scheduled = false;
15
+ async function repairRows(rows) {
16
+ let next = 0;
17
+ const worker = async () => {
18
+ while (next < rows.length) {
19
+ const entry = rows[next++];
20
+ try {
21
+ await writer.repairOne(entry.row);
22
+ entry.resolve();
23
+ }
24
+ catch (error) {
25
+ entry.reject(error);
26
+ }
27
+ }
28
+ };
29
+ await Promise.all(Array.from({ length: Math.min(maxInFlight, rows.length) }, worker));
30
+ }
31
+ async function settle(rows) {
32
+ if (rows.length === 1) {
33
+ const only = rows[0];
34
+ try {
35
+ await writer.writeOne(only.row);
36
+ only.resolve();
37
+ }
38
+ catch (error) {
39
+ only.reject(error);
40
+ }
41
+ return;
42
+ }
43
+ const batch = rows.map((entry) => entry.row);
44
+ let failure;
45
+ try {
46
+ await writer.writeBatch(batch);
47
+ for (const entry of rows)
48
+ entry.resolve();
49
+ return;
50
+ }
51
+ catch (error) {
52
+ failure = error;
53
+ }
54
+ if (!isRowDataSqlError(failure)) {
55
+ try {
56
+ await writer.retryBatch(batch);
57
+ for (const entry of rows)
58
+ entry.resolve();
59
+ return;
60
+ }
61
+ catch (error) {
62
+ failure = error;
63
+ }
64
+ }
65
+ if (isRowDataSqlError(failure)) {
66
+ await repairRows(rows);
67
+ return;
68
+ }
69
+ for (const entry of rows)
70
+ entry.reject(failure);
71
+ }
72
+ function drain() {
73
+ scheduled = false;
74
+ while (inFlight < maxInFlight && queue.length > 0) {
75
+ const rows = queue.length <= maxBatch ? queue : queue.slice(0, maxBatch);
76
+ queue = queue.length <= maxBatch ? [] : queue.slice(maxBatch);
77
+ inFlight += 1;
78
+ void settle(rows).finally(() => {
79
+ inFlight -= 1;
80
+ pending -= rows.length;
81
+ schedule();
82
+ });
83
+ }
84
+ }
85
+ function schedule() {
86
+ if (scheduled || inFlight >= maxInFlight || queue.length === 0)
87
+ return;
88
+ scheduled = true;
89
+ // A microtask, not a timer: fake-timer harnesses never stall a durable
90
+ // write, and rows queued while statements are in flight still share the
91
+ // next one.
92
+ queueMicrotask(drain);
93
+ }
94
+ return (row) => {
95
+ if (pending >= maxPending)
96
+ return writer.writeOne(row);
97
+ pending += 1;
98
+ return new Promise((resolve, reject) => {
99
+ queue.push({ row, resolve, reject });
100
+ schedule();
101
+ });
102
+ };
103
+ }
@@ -0,0 +1,2 @@
1
+ /** True when a lowercase bare host is a listing platform (or its subdomain) or a freemail host. */
2
+ export declare function isListedWebsitePlatform(host: string): boolean;
@@ -0,0 +1,26 @@
1
+ import { isFreemailDomain } from "./freemail-domains.js";
2
+ /**
3
+ * Hosts that list a company without being its website: social profiles, link-in-bio
4
+ * pages, shorteners, maps, calendars, chat links, code hosts, marketplaces, and
5
+ * company directories and review sites (an encyclopedia entry, an employer-review
6
+ * page, a B2B database profile). A
7
+ * company page whose "website" is one of these has no site of its own, and reading
8
+ * it would research the platform (`site:facebook.com`) and write the platform's domain
9
+ * into the company profile. A tenant subdomain of a site builder (`acme.wixsite.com`,
10
+ * `acme.github.io`) is the company's own site, so builders are deliberately absent.
11
+ */
12
+ const LISTED_WEBSITE_PLATFORM_HOSTS = [
13
+ "linkedin.com", "lnkd.in", "facebook.com", "fb.com", "fb.me", "instagram.com", "twitter.com", "x.com",
14
+ "threads.net", "tiktok.com", "youtube.com", "youtu.be", "pinterest.com", "snapchat.com", "reddit.com",
15
+ "medium.com", "linktr.ee", "linktree.com", "beacons.ai", "bio.link", "lnk.bio", "taplink.cc",
16
+ "campsite.bio", "bit.ly", "t.co", "tinyurl.com", "goo.gl", "g.page", "ow.ly", "buff.ly", "rebrand.ly",
17
+ "google.com", "calendly.com", "cal.com", "wa.me", "whatsapp.com", "t.me", "telegram.me", "discord.gg",
18
+ "discord.com", "github.com", "gitlab.com", "crunchbase.com", "wellfound.com", "angel.co", "yelp.com",
19
+ "tripadvisor.com", "amazon.com", "etsy.com", "ebay.com",
20
+ "wikipedia.org", "glassdoor.com", "zoominfo.com", "g2.com",
21
+ ];
22
+ /** True when a lowercase bare host is a listing platform (or its subdomain) or a freemail host. */
23
+ export function isListedWebsitePlatform(host) {
24
+ return LISTED_WEBSITE_PLATFORM_HOSTS.some((platform) => host === platform || host.endsWith(`.${platform}`))
25
+ || isFreemailDomain(host);
26
+ }
@@ -0,0 +1,90 @@
1
+ /**
2
+ * Newsletter analytics: what one sending-domain Sequence's bulk mail did, read
3
+ * from its SES ledger (`ox_runs.bulk_email_send_jobs` + `ox_sequencer.bulk_email_events`).
4
+ *
5
+ * Opens are estimates: Apple Mail Privacy Protection and corporate link scanners
6
+ * fetch the tracking pixel and links for the recipient, so every surface labels
7
+ * opens "estimated", and events SES flags as bots are never counted. Rates are
8
+ * fractions (0..1) over delivered mail, except the bounce rate, which is over
9
+ * sent mail (a bounced message was never delivered); null when the denominator is 0.
10
+ *
11
+ * Pure and browser-safe: the route, the web panel, the CLI and MCP share it.
12
+ */
13
+ /** A recipient's furthest outcome, most significant first when several apply. */
14
+ export declare const NEWSLETTER_RECIPIENT_STATUSES: readonly ["queued", "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed", "suppressed", "failed"];
15
+ export type NewsletterRecipientStatus = typeof NEWSLETTER_RECIPIENT_STATUSES[number];
16
+ export declare const NEWSLETTER_TIMELINE_INTERVALS: readonly ["hour", "day"];
17
+ export type NewsletterTimelineInterval = typeof NEWSLETTER_TIMELINE_INTERVALS[number];
18
+ /** The timeline covers the first seven days after the first send. */
19
+ export declare const NEWSLETTER_TIMELINE_DAYS = 7;
20
+ export declare const NEWSLETTER_RECIPIENTS_MAX_LIMIT = 200;
21
+ export declare const NEWSLETTER_RECIPIENTS_DEFAULT_LIMIT = 50;
22
+ export declare const NEWSLETTER_LINKS_LIMIT = 50;
23
+ export type NewsletterLinkStats = {
24
+ link: string;
25
+ unique_clicks: number;
26
+ total_clicks: number;
27
+ };
28
+ export type NewsletterTimelineBucket = {
29
+ at: string;
30
+ delivered: number;
31
+ /** Recipients whose first (non-bot) open fell in this bucket. */
32
+ opened: number;
33
+ /** Recipients whose first (non-bot) click fell in this bucket. */
34
+ clicked: number;
35
+ };
36
+ export type NewsletterAnalytics = {
37
+ recipients_targeted: number;
38
+ sent: number;
39
+ delivered: number;
40
+ opens: {
41
+ unique: number;
42
+ total: number;
43
+ estimated: true;
44
+ };
45
+ clicks: {
46
+ unique: number;
47
+ total: number;
48
+ };
49
+ bounces: {
50
+ hard: number;
51
+ soft: number;
52
+ };
53
+ complaints: number;
54
+ unsubscribes: number;
55
+ suppressed: number;
56
+ rates: {
57
+ open_rate: number | null;
58
+ click_rate: number | null;
59
+ bounce_rate: number | null;
60
+ complaint_rate: number | null;
61
+ unsubscribe_rate: number | null;
62
+ };
63
+ links: NewsletterLinkStats[];
64
+ timeline: {
65
+ interval: NewsletterTimelineInterval;
66
+ start: string | null;
67
+ buckets: NewsletterTimelineBucket[];
68
+ };
69
+ first_sent_at: string | null;
70
+ last_event_at: string | null;
71
+ };
72
+ export type NewsletterRecipient = {
73
+ email: string;
74
+ status: NewsletterRecipientStatus;
75
+ enrollment_id: string;
76
+ sent_at: string | null;
77
+ opens: number;
78
+ clicks: number;
79
+ last_event_at: string | null;
80
+ };
81
+ export type NewsletterRecipientsPage = {
82
+ recipients: NewsletterRecipient[];
83
+ status: NewsletterRecipientStatus | null;
84
+ total: number;
85
+ limit: number;
86
+ offset: number;
87
+ next_offset: number | null;
88
+ };
89
+ export declare function isNewsletterRecipientStatus(value: unknown): value is NewsletterRecipientStatus;
90
+ export declare function isNewsletterTimelineInterval(value: unknown): value is NewsletterTimelineInterval;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Newsletter analytics: what one sending-domain Sequence's bulk mail did, read
3
+ * from its SES ledger (`ox_runs.bulk_email_send_jobs` + `ox_sequencer.bulk_email_events`).
4
+ *
5
+ * Opens are estimates: Apple Mail Privacy Protection and corporate link scanners
6
+ * fetch the tracking pixel and links for the recipient, so every surface labels
7
+ * opens "estimated", and events SES flags as bots are never counted. Rates are
8
+ * fractions (0..1) over delivered mail, except the bounce rate, which is over
9
+ * sent mail (a bounced message was never delivered); null when the denominator is 0.
10
+ *
11
+ * Pure and browser-safe: the route, the web panel, the CLI and MCP share it.
12
+ */
13
+ /** A recipient's furthest outcome, most significant first when several apply. */
14
+ export const NEWSLETTER_RECIPIENT_STATUSES = [
15
+ "queued", "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed", "suppressed", "failed",
16
+ ];
17
+ export const NEWSLETTER_TIMELINE_INTERVALS = ["hour", "day"];
18
+ /** The timeline covers the first seven days after the first send. */
19
+ export const NEWSLETTER_TIMELINE_DAYS = 7;
20
+ export const NEWSLETTER_RECIPIENTS_MAX_LIMIT = 200;
21
+ export const NEWSLETTER_RECIPIENTS_DEFAULT_LIMIT = 50;
22
+ export const NEWSLETTER_LINKS_LIMIT = 50;
23
+ export function isNewsletterRecipientStatus(value) {
24
+ return typeof value === "string" && NEWSLETTER_RECIPIENT_STATUSES.includes(value);
25
+ }
26
+ export function isNewsletterTimelineInterval(value) {
27
+ return typeof value === "string" && NEWSLETTER_TIMELINE_INTERVALS.includes(value);
28
+ }
@@ -0,0 +1,20 @@
1
+ import { CliHttpError } from "./cli-http-error.js";
2
+ export declare const NEWSLETTER_TEST_MAX_RECIPIENTS = 5;
3
+ /** Test sends (requests, not emails) a workspace may make per day. */
4
+ export declare const NEWSLETTER_TEST_DAILY_LIMIT = 20;
5
+ export declare const NEWSLETTER_TEST_SUBJECT_PREFIX = "[Test] ";
6
+ /** SES message tag every test email carries; event apply and workspace health skip it. */
7
+ export declare const NEWSLETTER_TEST_SES_TAG = "oxygen_test";
8
+ export declare const NEWSLETTER_TEST_FAULT_CODES: {
9
+ readonly recipientNotMember: "test_send_recipient_not_member";
10
+ readonly notNewsletter: "test_send_not_newsletter";
11
+ readonly unavailable: "test_send_unavailable";
12
+ readonly failed: "test_send_failed";
13
+ };
14
+ export declare function testSendRecipientNotMemberError(recipients: readonly string[]): CliHttpError;
15
+ export declare function testSendNotNewsletterError(): CliHttpError;
16
+ export declare function testSendUnavailableError(): CliHttpError;
17
+ export declare function testSendFailedError(recipients: ReadonlyArray<{
18
+ email: string;
19
+ status: string;
20
+ }>): CliHttpError;
@@ -0,0 +1,46 @@
1
+ import { CliHttpError } from "./cli-http-error.js";
2
+ // A newsletter test send: one email step rendered as delivery renders it, sent
3
+ // to at most five verified addresses of the workspace's own members. Web, CLI
4
+ // and MCP share these limits and refusals (ADR 0023: fixed copy, a machine code
5
+ // and a next step; none names SES or another workspace).
6
+ export const NEWSLETTER_TEST_MAX_RECIPIENTS = 5;
7
+ /** Test sends (requests, not emails) a workspace may make per day. */
8
+ export const NEWSLETTER_TEST_DAILY_LIMIT = 20;
9
+ export const NEWSLETTER_TEST_SUBJECT_PREFIX = "[Test] ";
10
+ /** SES message tag every test email carries; event apply and workspace health skip it. */
11
+ export const NEWSLETTER_TEST_SES_TAG = "oxygen_test";
12
+ export const NEWSLETTER_TEST_FAULT_CODES = {
13
+ recipientNotMember: "test_send_recipient_not_member",
14
+ notNewsletter: "test_send_not_newsletter",
15
+ unavailable: "test_send_unavailable",
16
+ failed: "test_send_failed",
17
+ };
18
+ export function testSendRecipientNotMemberError(recipients) {
19
+ return new CliHttpError(400, NEWSLETTER_TEST_FAULT_CODES.recipientNotMember, "Test emails go only to verified email addresses of this workspace's members.", {
20
+ details: {
21
+ field: "to",
22
+ recipients: [...recipients],
23
+ retryable: false,
24
+ next_step: "Send to your own address or a teammate's verified address; list them with `oxygen sequences test-send <sequence> --list-recipients`.",
25
+ },
26
+ exitCode: 1,
27
+ });
28
+ }
29
+ export function testSendNotNewsletterError() {
30
+ return new CliHttpError(409, NEWSLETTER_TEST_FAULT_CODES.notNewsletter, "Test sends are for Sequences that send through a sending domain.", {
31
+ details: { retryable: false, next_step: "Choose a sending domain in the Sequence's Sending settings, then send a test." },
32
+ exitCode: 1,
33
+ });
34
+ }
35
+ export function testSendUnavailableError() {
36
+ return new CliHttpError(503, NEWSLETTER_TEST_FAULT_CODES.unavailable, "Test emails can't be sent right now.", {
37
+ details: { retryable: true, next_step: "Try again in a few minutes." },
38
+ exitCode: 1,
39
+ });
40
+ }
41
+ export function testSendFailedError(recipients) {
42
+ return new CliHttpError(502, NEWSLETTER_TEST_FAULT_CODES.failed, "The test email could not be sent.", {
43
+ details: { recipients: [...recipients], retryable: true, next_step: "Check the sending domain is active, then try again." },
44
+ exitCode: 1,
45
+ });
46
+ }
@@ -103,11 +103,22 @@ export declare function readCopilotAttachmentObject(input: {
103
103
  contentType: string | null;
104
104
  truncated: boolean;
105
105
  }>;
106
+ /** Authenticated callers retain authorization; never mint a transferable GET URL. */
107
+ export declare function openCopilotAttachmentObject(input: {
108
+ storageKey: string;
109
+ etag: string;
110
+ window?: {
111
+ offset: number;
112
+ limit: number;
113
+ };
114
+ signal?: AbortSignal;
115
+ }): Promise<ReadableStream<Uint8Array>>;
106
116
  export declare function getCopilotAttachmentObjectMetadata(input: {
107
117
  storageKey: string;
108
118
  }): Promise<{
109
119
  contentLength: number | null;
110
120
  contentType: string | null;
121
+ etag: string | null;
111
122
  }>;
112
123
  /**
113
124
  * Read the LEADING BYTES of a staged import back out of the bucket.
@@ -252,10 +252,22 @@ export async function readCopilotAttachmentObject(input) {
252
252
  truncated,
253
253
  };
254
254
  }
255
+ /** Authenticated callers retain authorization; never mint a transferable GET URL. */
256
+ export async function openCopilotAttachmentObject(input) {
257
+ const { client, config } = resolveClient();
258
+ const result = await client.send(new GetObjectCommand({
259
+ Bucket: config.bucket, Key: input.storageKey, IfMatch: input.etag,
260
+ ...(input.window ? { Range: `bytes=${input.window.offset}-${input.window.offset + input.window.limit - 1}` } : {}),
261
+ }), input.signal ? { abortSignal: input.signal } : {});
262
+ if (!result.Body)
263
+ throw new Error("Attachment object had no body.");
264
+ return result.Body.transformToWebStream();
265
+ }
255
266
  export async function getCopilotAttachmentObjectMetadata(input) {
256
267
  const { client, config } = resolveClient();
257
268
  const result = await client.send(new HeadObjectCommand({ Bucket: config.bucket, Key: input.storageKey }));
258
269
  return {
270
+ etag: result.ETag ?? null,
259
271
  contentLength: typeof result.ContentLength === "number" ? result.ContentLength : null,
260
272
  contentType: typeof result.ContentType === "string" ? result.ContentType : null,
261
273
  };
@@ -94,6 +94,15 @@ export declare function resolveDefaultTriggerRunCreditCeilingForPlan(resolution:
94
94
  export declare function resolveDefaultConnectionCreditCeilingForPlan(resolution: PlanSpendResolution, options?: RepricingOptions): number;
95
95
  /** The same default for one standing or webhook table auto-run batch. */
96
96
  export declare function resolveDefaultAutoRunBatchCreditCeilingForPlan(resolution: PlanSpendResolution, options?: RepricingOptions): number | null;
97
+ /**
98
+ * PROPOSED defaults, not yet a product decision: newsletter (sending-domain)
99
+ * emails one workspace may reserve per UTC day. Newsletters are paid-only, so
100
+ * free is 0. The staff override and the workspace's share of the SES quota
101
+ * (`bulkEmailWorkspaceDailyAllowance`) can only lower this.
102
+ */
103
+ export declare const BULK_EMAIL_DAILY_CAP_PER_PLAN_BAND: Readonly<Record<PlanBand, number>>;
104
+ /** The largest plan cap: no sending domain's own daily ceiling may exceed it. */
105
+ export declare const BULK_EMAIL_MAX_DAILY_CAP: number;
97
106
  /**
98
107
  * Public webhook ingress (repricing 2026-09, decision L4.4, ratified
99
108
  * 2026-09-26): deliveries a minute that one webhook target (a Table endpoint,
@@ -203,6 +203,23 @@ export function resolveDefaultAutoRunBatchCreditCeilingForPlan(resolution, optio
203
203
  function bandSpendResolution(band) {
204
204
  return { planTier: band === "free" ? null : `oxygen_${band}`, limitsTier: PLAN_BAND_LIMITS_TIER[band] };
205
205
  }
206
+ /**
207
+ * PROPOSED defaults, not yet a product decision: newsletter (sending-domain)
208
+ * emails one workspace may reserve per UTC day. Newsletters are paid-only, so
209
+ * free is 0. The staff override and the workspace's share of the SES quota
210
+ * (`bulkEmailWorkspaceDailyAllowance`) can only lower this.
211
+ */
212
+ export const BULK_EMAIL_DAILY_CAP_PER_PLAN_BAND = Object.freeze({
213
+ free: 0,
214
+ "49": 5_000,
215
+ "99": 10_000,
216
+ "199": 25_000,
217
+ "499": 50_000,
218
+ "999": 100_000,
219
+ "1999": 250_000,
220
+ });
221
+ /** The largest plan cap: no sending domain's own daily ceiling may exceed it. */
222
+ export const BULK_EMAIL_MAX_DAILY_CAP = Math.max(...Object.values(BULK_EMAIL_DAILY_CAP_PER_PLAN_BAND));
206
223
  /**
207
224
  * Public webhook ingress (repricing 2026-09, decision L4.4, ratified
208
225
  * 2026-09-26): deliveries a minute that one webhook target (a Table endpoint,
@@ -49,7 +49,7 @@
49
49
  import type { PlanTier, PricingPlanDefinition } from "./billing.js";
50
50
  import { CREDIT_GATE_RETIRED_CAPABILITIES, isCapabilityRetiredByCreditGate } from "./credit-gate.js";
51
51
  import { type RepricingOptions } from "./repricing.js";
52
- export declare const PLAN_GATED_CAPABILITIES: readonly ["sender_connect", "linkedin_connect", "sequence_dispatch", "publishing_connect", "publishing_deliver", "managed_email_infrastructure", "byok_provider_keys"];
52
+ export declare const PLAN_GATED_CAPABILITIES: readonly ["sender_connect", "linkedin_connect", "sequence_dispatch", "publishing_connect", "publishing_deliver", "managed_email_infrastructure", "byok_provider_keys", "bulk_email"];
53
53
  export type PlanGatedCapability = (typeof PLAN_GATED_CAPABILITIES)[number];
54
54
  /**
55
55
  * Every tier except `free` unblocks every gated capability.
@@ -83,7 +83,7 @@ export declare function isPlanGatedCapability(value: unknown): value is PlanGate
83
83
  * (`assertCreditGateArmed`). Until then every one of them stays walled exactly
84
84
  * as before.
85
85
  *
86
- * Four capabilities stay walled under the gate:
86
+ * Five capabilities stay walled under the gate:
87
87
  * - `linkedin_connect` and `sender_connect`: every sending account connects
88
88
  * only on a plan (founder, current chat, 2026-10-12), whatever the balance.
89
89
  * That covers a LinkedIn account, a mailbox (imported or bought), a WhatsApp
@@ -94,6 +94,8 @@ export declare function isPlanGatedCapability(value: unknown): value is PlanGate
94
94
  * Instagram, TikTok, YouTube and Facebook, which have no reservation price yet
95
95
  * (P-18). Connecting them without one would make them free and unmetered, so
96
96
  * they stay on the plan until that price is ratified.
97
+ * - `bulk_email`: newsletters share one sending reputation across customers, so
98
+ * they stay on a plan whatever the balance (user, current chat, 2026-10-21).
97
99
  */
98
100
  export { CREDIT_GATE_RETIRED_CAPABILITIES, isCapabilityRetiredByCreditGate };
99
101
  /**
@@ -56,6 +56,7 @@ export const PLAN_GATED_CAPABILITIES = [
56
56
  "publishing_deliver",
57
57
  "managed_email_infrastructure",
58
58
  "byok_provider_keys",
59
+ "bulk_email",
59
60
  ];
60
61
  /**
61
62
  * Every tier except `free` unblocks every gated capability.
@@ -110,6 +111,14 @@ export const PLAN_GATED_CAPABILITY_COPY = {
110
111
  freeAlternative: "Every provider in the catalog already works on Free using OXYGEN's managed keys and your credits — including enrichment, AI columns, and phone lookups. Bringing your own key is what needs a plan.",
111
112
  deepLinkPath: "/settings/integrations",
112
113
  },
114
+ // Newsletters through OXYGEN's shared sending infrastructure are paid-only
115
+ // (user, current chat, 2026-10-21), whatever the balance: a free workspace's
116
+ // list must never reach the reputation every customer shares.
117
+ bulk_email: {
118
+ label: "Sending newsletters",
119
+ freeAlternative: "Subscription lists and newsletter Sequences can be set up on Free. Adding a sending domain and sending to subscribers is what needs a plan.",
120
+ deepLinkPath: "/sequencer/accounts?tab=newsletter",
121
+ },
113
122
  };
114
123
  export function isPlanGatedCapability(value) {
115
124
  return (typeof value === "string"
@@ -127,7 +136,7 @@ export function isPlanGatedCapability(value) {
127
136
  * (`assertCreditGateArmed`). Until then every one of them stays walled exactly
128
137
  * as before.
129
138
  *
130
- * Four capabilities stay walled under the gate:
139
+ * Five capabilities stay walled under the gate:
131
140
  * - `linkedin_connect` and `sender_connect`: every sending account connects
132
141
  * only on a plan (founder, current chat, 2026-10-12), whatever the balance.
133
142
  * That covers a LinkedIn account, a mailbox (imported or bought), a WhatsApp
@@ -138,6 +147,8 @@ export function isPlanGatedCapability(value) {
138
147
  * Instagram, TikTok, YouTube and Facebook, which have no reservation price yet
139
148
  * (P-18). Connecting them without one would make them free and unmetered, so
140
149
  * they stay on the plan until that price is ratified.
150
+ * - `bulk_email`: newsletters share one sending reputation across customers, so
151
+ * they stay on a plan whatever the balance (user, current chat, 2026-10-21).
141
152
  */
142
153
  export { CREDIT_GATE_RETIRED_CAPABILITIES, isCapabilityRetiredByCreditGate };
143
154
  /**