@hogsend/engine 0.62.0 → 0.64.0

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.
@@ -1,3 +1,4 @@
1
+ import { normalizeReturnPathLabel } from "@hogsend/core";
1
2
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
3
  import type { AppEnv } from "../../app.js";
3
4
  import { errorSchema } from "../../lib/schemas.js";
@@ -47,13 +48,25 @@ const TestModeStateSchema = z.object({
47
48
  fromOverride: z.string().nullable(),
48
49
  });
49
50
 
50
- // Mirrors the pinned `EngineDomainStatus` shape.
51
+ // Mirrors the pinned `SendingDomainGuidance` shape (lib/sending-domain-guidance.ts).
52
+ // `.readonly()` matches the interface's frozen `readonly string[]` labels.
53
+ const SendingDomainGuidanceSchema = z.object({
54
+ title: z.string(),
55
+ body: z.string(),
56
+ note: z.string(),
57
+ recommendedLabels: z.array(z.string()).readonly(),
58
+ });
59
+
60
+ // Mirrors the pinned `EngineDomainStatus` shape. `returnPathSupported` is
61
+ // optional there for wire skew only — this engine always sends it.
51
62
  const EngineDomainStatusSchema = z.object({
52
63
  domain: z.string().nullable(),
53
64
  providerId: z.string(),
54
65
  supported: z.boolean(),
66
+ returnPathSupported: z.boolean().optional(),
55
67
  status: DomainStatusSchema.nullable(),
56
68
  testMode: TestModeStateSchema,
69
+ guidance: SendingDomainGuidanceSchema,
57
70
  });
58
71
 
59
72
  /** Pinned domain validation regex (PROJECT_SPEC §e). */
@@ -76,6 +89,62 @@ const providerErrorResponse = {
76
89
  description: "The provider rejected or failed the domains request",
77
90
  } as const;
78
91
 
92
+ /**
93
+ * A provider refusal that is the OPERATOR'S to act on, forwarded verbatim
94
+ * instead of being buried under the blanket 502.
95
+ *
96
+ * The case this exists for: Hogsend Email answers `409 domain_not_owned` when a
97
+ * domain is claimed by another account, and its message carries the remedy.
98
+ * Flattened to "domains request to provider failed: …" with a 502, Studio
99
+ * rendered an opaque gateway error for a request that was well-formed,
100
+ * authenticated, and had a real answer waiting in it.
101
+ *
102
+ * 409 ONLY, and the narrowness is the point. A provider's 401 or 403 is OUR
103
+ * misconfiguration — a bad API key, a revoked token — and forwarding those
104
+ * would tell the customer their request was at fault for an outage they cannot
105
+ * fix. 502 stays the answer for everything genuinely opaque.
106
+ *
107
+ * The shape is matched STRUCTURALLY (a numeric `status`, a non-empty string
108
+ * `error` slug) rather than by class: the engine must not import a provider
109
+ * package to type-check a provider's error, and every plugin already models a
110
+ * refusal this way.
111
+ */
112
+ const conflictResponse = {
113
+ content: {
114
+ "application/json": {
115
+ schema: z.object({
116
+ /** The provider's own slug, verbatim — e.g. `domain_not_owned`. */
117
+ error: z.string(),
118
+ /** The provider's sentence. It carries the remedy; render it. */
119
+ message: z.string(),
120
+ }),
121
+ },
122
+ },
123
+ description:
124
+ "The provider refused because the request conflicts with the world " +
125
+ "(e.g. the domain is already claimed by another account). The message " +
126
+ "carries the remedy.",
127
+ } as const;
128
+
129
+ /** The forwarded refusal, or `null` when this is an opaque provider failure. */
130
+ const providerConflictBody = (
131
+ err: unknown,
132
+ ): { error: string; message: string } | null => {
133
+ if (typeof err !== "object" || err === null) return null;
134
+ const { status, error, message } = err as {
135
+ status?: unknown;
136
+ error?: unknown;
137
+ message?: unknown;
138
+ };
139
+ if (status !== 409) return null;
140
+ if (typeof error !== "string" || error.length === 0) return null;
141
+ return {
142
+ error,
143
+ message:
144
+ typeof message === "string" && message.length > 0 ? message : error,
145
+ };
146
+ };
147
+
79
148
  const getDomainRoute = createRoute({
80
149
  method: "get",
81
150
  path: "/",
@@ -121,6 +190,7 @@ const addDomainRoute = createRoute({
121
190
  },
122
191
  description: "Domain registered (idempotent) — fresh status",
123
192
  },
193
+ 409: conflictResponse,
124
194
  501: {
125
195
  content: { "application/json": { schema: errorSchema } },
126
196
  description: "The active provider has no domains capability",
@@ -145,6 +215,7 @@ const verifyDomainRoute = createRoute({
145
215
  content: { "application/json": { schema: errorSchema } },
146
216
  description: "No sending domain configured (EMAIL_DOMAIN / EMAIL_FROM)",
147
217
  },
218
+ 409: conflictResponse,
148
219
  501: {
149
220
  content: { "application/json": { schema: errorSchema } },
150
221
  description: "The active provider has no domains capability",
@@ -153,6 +224,74 @@ const verifyDomainRoute = createRoute({
153
224
  },
154
225
  });
155
226
 
227
+ /**
228
+ * The branded return path, both directions (PRD 20). It carries BOUNCE
229
+ * traffic: on routes bounces via `<label>.<domain>` (two extra DNS records,
230
+ * MX + SPF) so mailbox UIs stop showing "via <provider>" and SPF aligns with
231
+ * the customer's own domain; off reverts to the provider default and the
232
+ * domain stays fully verified on its base records. It changes nothing about
233
+ * where a customer's incoming mail lands. Off is the default — nothing here
234
+ * may switch it on implicitly.
235
+ */
236
+ const setReturnPathRoute = createRoute({
237
+ method: "post",
238
+ path: "/return-path",
239
+ tags: ["Admin — Domain"],
240
+ summary: "Switch the branded return path (custom MAIL FROM) on or off",
241
+ description:
242
+ "The return path carries bounce traffic. On adds two DNS records (MX + " +
243
+ 'SPF) at `<label>.<domain>` so mailbox UIs stop showing "via ' +
244
+ '<provider>"; off reverts to the provider default and the domain stays ' +
245
+ "fully verified on its base records. Off is the default.",
246
+ request: {
247
+ body: {
248
+ content: {
249
+ "application/json": {
250
+ schema: z.object({
251
+ enabled: z.boolean(),
252
+ // Single DNS label (`notifications` → `notifications.<domain>`).
253
+ // Validated in the handler with the core rule so the rejection
254
+ // can NAME the offending label, not cite a pattern.
255
+ label: z.string().optional(),
256
+ }),
257
+ },
258
+ },
259
+ },
260
+ },
261
+ responses: {
262
+ 200: {
263
+ content: {
264
+ "application/json": {
265
+ schema: z.object({
266
+ // What the provider now holds — read back after the write, never
267
+ // an echo of the request.
268
+ returnPath: z.object({
269
+ enabled: z.boolean(),
270
+ mailFromDomain: z.string().nullable(),
271
+ }),
272
+ status: EngineDomainStatusSchema,
273
+ }),
274
+ },
275
+ },
276
+ description:
277
+ "Return path switched — read-back state plus fresh domain status " +
278
+ "(the MX + SPF records report as pending when switched on)",
279
+ },
280
+ 400: {
281
+ content: { "application/json": { schema: errorSchema } },
282
+ description: "Invalid return-path label, or no sending domain configured",
283
+ },
284
+ 409: conflictResponse,
285
+ 501: {
286
+ content: { "application/json": { schema: errorSchema } },
287
+ description:
288
+ "The active provider has no domains capability, or its domains " +
289
+ "capability cannot manage the return path",
290
+ },
291
+ 502: providerErrorResponse,
292
+ },
293
+ });
294
+
156
295
  export const domainRouter = new OpenAPIHono<AppEnv>()
157
296
  .openapi(getDomainRoute, async (c) => {
158
297
  const { domainStatus, emailProvider } = c.get("container");
@@ -183,6 +322,8 @@ export const domainRouter = new OpenAPIHono<AppEnv>()
183
322
  const status = await domainStatus.getStatus({ refresh: true });
184
323
  return c.json(status, 200);
185
324
  } catch (err) {
325
+ const conflict = providerConflictBody(err);
326
+ if (conflict) return c.json(conflict, 409);
186
327
  return c.json(
187
328
  providerErrorBody(emailProvider.meta?.id ?? "email", err),
188
329
  502,
@@ -214,6 +355,78 @@ export const domainRouter = new OpenAPIHono<AppEnv>()
214
355
  const status = await domainStatus.getStatus({ refresh: true });
215
356
  return c.json(status, 200);
216
357
  } catch (err) {
358
+ const conflict = providerConflictBody(err);
359
+ if (conflict) return c.json(conflict, 409);
360
+ return c.json(
361
+ providerErrorBody(emailProvider.meta?.id ?? "email", err),
362
+ 502,
363
+ );
364
+ }
365
+ })
366
+ .openapi(setReturnPathRoute, async (c) => {
367
+ const { domainStatus, emailProvider } = c.get("container");
368
+ const { enabled, label } = c.req.valid("json");
369
+
370
+ // TWO different unsupported cases, one deliberate answer each: no
371
+ // `domains` capability at all, and a `domains` capability without
372
+ // `setReturnPath`. Both are capability gaps, not engine errors — a throw
373
+ // on the second would read as a bug in a deploy that simply cannot do
374
+ // this. Same idiom as the other POSTs, no second one invented.
375
+ if (!emailProvider.domains) {
376
+ return c.json({ error: "provider_unsupported" }, 501);
377
+ }
378
+ const capability = emailProvider.domains;
379
+ if (!capability.setReturnPath) {
380
+ return c.json({ error: "provider_unsupported" }, 501);
381
+ }
382
+
383
+ // PRD 15's label rule, reused from core — rejected BEFORE any provider
384
+ // traffic, and the rejection names the offending label.
385
+ let normalizedLabel: string | undefined;
386
+ if (label !== undefined) {
387
+ const normalized = normalizeReturnPathLabel(label);
388
+ if (normalized === null) {
389
+ return c.json(
390
+ {
391
+ error:
392
+ `"${label}" is not a valid subdomain label. Use one DNS ` +
393
+ "label: lowercase letters, digits and hyphens, starting and " +
394
+ "ending alphanumeric, 63 characters or fewer, no dots.",
395
+ },
396
+ 400,
397
+ );
398
+ }
399
+ normalizedLabel = normalized;
400
+ }
401
+
402
+ try {
403
+ const current = await domainStatus.getStatus();
404
+ if (!current.domain) {
405
+ return c.json({ error: "no_domain_configured" }, 400);
406
+ }
407
+
408
+ const returnPath = await capability.setReturnPath({
409
+ domain: current.domain,
410
+ enabled,
411
+ ...(normalizedLabel === undefined ? {} : { label: normalizedLabel }),
412
+ });
413
+
414
+ // Bust + refresh so this answer AND every subsequent GET reflect the
415
+ // switch rather than a pre-toggle cache entry.
416
+ const status = await domainStatus.getStatus({ refresh: true });
417
+ return c.json(
418
+ {
419
+ returnPath: {
420
+ enabled: returnPath.enabled,
421
+ mailFromDomain: returnPath.mailFromDomain,
422
+ },
423
+ status,
424
+ },
425
+ 200,
426
+ );
427
+ } catch (err) {
428
+ const conflict = providerConflictBody(err);
429
+ if (conflict) return c.json(conflict, 409);
217
430
  return c.json(
218
431
  providerErrorBody(emailProvider.meta?.id ?? "email", err),
219
432
  502,