@aitne/daemon 0.1.7 → 0.1.8

package/dist/api/routes/mail.js

@@ -16,7 +16,24 @@ import { searchMail } from "../../services/mail/mail-search.js";
 import { extractMailHtmlBody, renderExtractedMailHtmlBody, } from "../../services/mail/html-to-plaintext.js";
 import { INTEGRATION_DESCRIPTORS, } from "@aitne/shared";
 import { readIntegrations } from "../../db/integrations-store.js";
+import { composeIssue, respondWithAgentError } from "../helpers/agent-errors.js";
 const logger = createLogger("mail-api");
+/**
+ * Build the agent-consumable 501 response for an operation the resolved
+ * provider doesn't implement (e.g. IMAP can't manage drafts). The legacy
+ * shape `{ error: "not_implemented", message: "<op> not supported on <kind>" }`
+ * is preserved via legacyFields so existing tests keep matching.
+ */
+function notImplementedResponse(c, operation, providerKind) {
+    const message = `${operation} not supported on ${providerKind}`;
+    return respondWithAgentError(c, 501, [
+        composeIssue("mail.not_implemented", {
+            field: `provider.${operation}`,
+            received: providerKind,
+            hint: `${message}. Try a Gmail or Outlook account, or use a different operation.`,
+        }),
+    ], { legacyFields: { message } });
+}
 const ALL_KINDS = [
     "gmail",
     "outlook",
@@ -158,14 +175,25 @@ export function createMailRoutes(deps) {
             return parsedBody.response;
         const candidate = parsedBody.body?.enabledKinds;
         if (!Array.isArray(candidate)) {
-            return c.json({ error: "invalid_body", message: "enabledKinds must be an array" }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("mail.invalid_body", {
+                    field: "enabledKinds",
+                    received: candidate === undefined ? "<missing>" : typeof candidate,
+                    hint: "enabledKinds must be an array of provider kinds (e.g. ['gmail','outlook','imap']). Empty array disables all.",
+                }),
+            ], { legacyFields: { message: "enabledKinds must be an array" } });
         }
         const settingsStore = getSettingsStore();
         const result = await applyConfigUpdates(deps.config, settingsStore, {
             enabledMailProviders: candidate,
         });
         if (Object.keys(result.errors).length > 0) {
-            return c.json({ error: "validation_failed", errors: result.errors }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("mail.validation_failed", {
+                    field: "enabledKinds",
+                    received: candidate,
+                }),
+            ], { legacyFields: { errors: result.errors } });
         }
         const newKinds = deps.config.enabledMailProviders;
         const registry = deps.services.mail;
@@ -209,10 +237,22 @@ export function createMailRoutes(deps) {
     // Headless environments (SSH, WSL) should use /mail/accounts/device-code.
     app.post("/mail/accounts", async (c) => {
         const registry = deps.services.mail;
-        if (!registry)
-            return c.json({ error: "mail_not_configured" }, 503);
-        if (!deps.blobStore)
-            return c.json({ error: "blob_store_unavailable" }, 503);
+        if (!registry) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
+        if (!deps.blobStore) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.blob_store_unavailable", {
+                    field: "deps.blobStore",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         const parsedBody = await readJsonBody(c);
         if (!parsedBody.ok)
             return parsedBody.response;
@@ -223,26 +263,42 @@ export function createMailRoutes(deps) {
             // /config/google-auth. Additional Gmail accounts still need a
             // per-account Google OAuth credential store and are intentionally
             // not wired up yet.
-            return c.json({
-                error: "not_implemented",
-                message: "Additional Gmail accounts are not implemented yet. The primary Gmail identity is configured through /config/google-auth and is exposed on the unified /mail/* surface automatically.",
-            }, 501);
+            return respondWithAgentError(c, 501, [
+                composeIssue("mail.not_implemented", {
+                    field: "kind",
+                    received: "gmail",
+                    hint: "Additional Gmail accounts are not implemented yet. The primary Gmail identity is configured through /config/google-auth and is exposed on the unified /mail/* surface automatically.",
+                }),
+            ], {
+                legacyFields: {
+                    message: "Additional Gmail accounts are not implemented yet. The primary Gmail identity is configured through /config/google-auth and is exposed on the unified /mail/* surface automatically.",
+                },
+            });
         }
         if (body?.kind !== "outlook") {
-            return c.json({
-                error: "unsupported_kind",
-                message: "Only outlook is supported on this endpoint. Yahoo/iCloud use POST /config/mail/app-password. The primary Gmail account uses /config/google-auth; extra Gmail accounts are not implemented.",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("mail.unsupported_kind", {
+                    field: "kind",
+                    received: body?.kind ?? "<missing>",
+                    hint: "Only outlook is supported on this endpoint. Yahoo/iCloud use POST /config/mail/app-password. The primary Gmail account uses /config/google-auth; extra Gmail accounts are not implemented.",
+                }),
+            ], {
+                legacyFields: {
+                    message: "Only outlook is supported on this endpoint. Yahoo/iCloud use POST /config/mail/app-password. The primary Gmail account uses /config/google-auth; extra Gmail accounts are not implemented.",
+                },
+            });
         }
         // §UI v2 auth-then-enable: registration is allowed regardless of
         // enabledMailProviders. The provider becomes live only when the user
         // toggles "Enable" on the dashboard mail card.
         const clientConfig = await loadOutlookClientConfig(deps.blobStore);
         if (!clientConfig) {
-            return c.json({
-                error: "outlook_client_config_missing",
-                message: "PUT /api/config/mail/outlook/client-config first.",
-            }, 412);
+            return respondWithAgentError(c, 412, [
+                composeIssue("mail.outlook_client_config_missing", {
+                    field: "outlookClientConfig",
+                    received: "<unset>",
+                }),
+            ], { legacyFields: { message: "PUT /api/config/mail/outlook/client-config first." } });
         }
         let oauthResult;
         try {
@@ -250,7 +306,12 @@ export function createMailRoutes(deps) {
         }
         catch (err) {
             if (err instanceof OAuthLoopbackTimeoutError) {
-                return c.json({ error: "oauth_timeout", message: err.message }, 408);
+                return respondWithAgentError(c, 408, [
+                    composeIssue("mail.oauth_timeout", {
+                        field: "outlook.oauth",
+                        received: err.message,
+                    }),
+                ], { legacyFields: { message: err.message } });
             }
             if (err instanceof OAuthLoopbackError) {
                 return c.json({ error: err.code, message: err.message }, 400);
@@ -286,23 +347,46 @@ export function createMailRoutes(deps) {
     // in their browser, so this endpoint may remain open for several minutes.
     app.post("/mail/accounts/device-code", async (c) => {
         const registry = deps.services.mail;
-        if (!registry)
-            return c.json({ error: "mail_not_configured" }, 503);
-        if (!deps.blobStore)
-            return c.json({ error: "blob_store_unavailable" }, 503);
+        if (!registry) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
+        if (!deps.blobStore) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.blob_store_unavailable", {
+                    field: "deps.blobStore",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         const parsedBody = await readJsonBody(c);
         if (!parsedBody.ok)
             return parsedBody.response;
         const body = parsedBody.body;
         if (body?.kind !== "outlook") {
-            return c.json({ error: "unsupported_kind" }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("mail.unsupported_kind", {
+                    field: "kind",
+                    received: body?.kind ?? "<missing>",
+                    hint: "Device-code flow is Outlook-only on this endpoint. Use POST /mail/accounts for other providers.",
+                }),
+            ]);
         }
         // §UI v2 auth-then-enable: registration allowed regardless of
         // enabledMailProviders. The Enable toggle on the dashboard mail card
         // governs whether the agent observes this account.
         const clientConfig = await loadOutlookClientConfig(deps.blobStore);
         if (!clientConfig) {
-            return c.json({ error: "outlook_client_config_missing" }, 412);
+            return respondWithAgentError(c, 412, [
+                composeIssue("mail.outlook_client_config_missing", {
+                    field: "outlookClientConfig",
+                    received: "<unset>",
+                }),
+            ], { legacyFields: { message: "PUT /api/config/mail/outlook/client-config first." } });
         }
         const label = typeof body?.label === "string" ? body.label : undefined;
         return streamSSE(c, async (stream) => {
@@ -357,8 +441,14 @@ export function createMailRoutes(deps) {
     // provider enabled.
     app.patch("/mail/accounts/:accountId", async (c) => {
         const registry = deps.services.mail;
-        if (!registry)
-            return c.json({ error: "mail_not_configured" }, 503);
+        if (!registry) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         const accountId = c.req.param("accountId");
         const parsedBody = await readJsonBody(c);
         if (!parsedBody.ok)
@@ -368,19 +458,35 @@ export function createMailRoutes(deps) {
             return c.json({ error: "invalid_body", message: "active: boolean required" }, 400);
         }
         const updated = await registry.setActive(accountId, active);
-        if (!updated)
-            return c.json({ error: "not_found" }, 404);
+        if (!updated) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("mail.account_not_found", {
+                    field: "accountId",
+                    received: c.req.param("id") ?? "<unknown>",
+                }),
+            ]);
+        }
         return c.json({ status: "updated", account: updated });
     });
     app.delete("/mail/accounts/:accountId", async (c) => {
         const registry = deps.services.mail;
         if (!registry) {
-            return c.json({ error: "mail_not_configured" }, 503);
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
         }
         const accountId = c.req.param("accountId");
         const removed = await registry.removeAccount(accountId);
         if (!removed) {
-            return c.json({ error: "not_found" }, 404);
+            return respondWithAgentError(c, 404, [
+                composeIssue("mail.account_not_found", {
+                    field: "accountId",
+                    received: accountId,
+                }),
+            ]);
         }
         return c.json({ status: "removed", accountId });
     });
@@ -389,8 +495,14 @@ export function createMailRoutes(deps) {
     // Stored separately from per-account token cache.
     // ──────────────────────────────────────────────────────────────────────────
     app.get("/config/mail/outlook/client-config", async (c) => {
-        if (!deps.blobStore)
-            return c.json({ error: "blob_store_unavailable" }, 503);
+        if (!deps.blobStore) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.blob_store_unavailable", {
+                    field: "deps.blobStore",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         const config = await loadOutlookClientConfig(deps.blobStore);
         if (!config)
             return c.json({ configured: false }, 200);
@@ -399,8 +511,14 @@ export function createMailRoutes(deps) {
         return c.json({ configured: true, clientId: config.clientId, tenant: config.tenant });
     });
     app.put("/config/mail/outlook/client-config", async (c) => {
-        if (!deps.blobStore)
-            return c.json({ error: "blob_store_unavailable" }, 503);
+        if (!deps.blobStore) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.blob_store_unavailable", {
+                    field: "deps.blobStore",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         const parsedBody = await readJsonBody(c);
         if (!parsedBody.ok)
             return parsedBody.response;
@@ -408,7 +526,13 @@ export function createMailRoutes(deps) {
         const clientId = candidate?.clientId;
         const tenant = candidate?.tenant;
         if (typeof clientId !== "string" || clientId.length === 0) {
-            return c.json({ error: "invalid_body", message: "clientId required" }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("mail.invalid_body", {
+                    field: "clientId",
+                    received: clientId === undefined ? "<missing>" : typeof clientId,
+                    hint: "Outlook client config requires `clientId` (the Azure AD app's id). Optionally `tenant` (defaults to 'common').",
+                }),
+            ], { legacyFields: { message: "clientId required" } });
         }
         const resolved = {
             clientId,
@@ -418,8 +542,14 @@ export function createMailRoutes(deps) {
         return c.json({ status: "saved", clientId: resolved.clientId, tenant: resolved.tenant });
     });
     app.delete("/config/mail/outlook/client-config", async (c) => {
-        if (!deps.blobStore)
-            return c.json({ error: "blob_store_unavailable" }, 503);
+        if (!deps.blobStore) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.blob_store_unavailable", {
+                    field: "deps.blobStore",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         await deps.blobStore.remove(OUTLOOK_CLIENT_CONFIG_BLOB);
         return c.json({ status: "removed" });
     });
@@ -429,8 +559,14 @@ export function createMailRoutes(deps) {
     // http.Server inside runLoopbackOAuth.
     app.post("/config/mail/app-password", async (c) => {
         const registry = deps.services.mail;
-        if (!registry)
-            return c.json({ error: "mail_not_configured" }, 503);
+        if (!registry) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         const parsedBody = await readJsonBody(c);
         if (!parsedBody.ok)
             return parsedBody.response;
@@ -509,17 +645,32 @@ export function createMailRoutes(deps) {
     // then resets `auth_status` to `healthy`.
     app.post("/config/mail/app-password/:accountId/refresh", async (c) => {
         const registry = deps.services.mail;
-        if (!registry)
-            return c.json({ error: "mail_not_configured" }, 503);
+        if (!registry) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         const accountId = c.req.param("accountId");
         const account = registry.getAccount(accountId);
-        if (!account)
-            return c.json({ error: "not_found" }, 404);
+        if (!account) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("mail.account_not_found", {
+                    field: "accountId",
+                    received: accountId,
+                }),
+            ]);
+        }
         if (account.kind !== "yahoo" && account.kind !== "icloud") {
-            return c.json({
-                error: "unsupported_kind",
-                message: "App-password refresh only supports yahoo / icloud. Outlook re-authenticates via the OAuth loopback flow.",
-            }, 400);
+            return respondWithAgentError(c, 400, [
+                composeIssue("mail.unsupported_kind", {
+                    field: "account.kind",
+                    received: account.kind,
+                    hint: "App-password refresh only supports yahoo / icloud. Outlook re-authenticates via the OAuth loopback flow.",
+                }),
+            ], { legacyFields: { message: "App-password refresh only supports yahoo / icloud. Outlook re-authenticates via the OAuth loopback flow." } });
         }
         const parsedBody = await readJsonBody(c);
         if (!parsedBody.ok)
@@ -557,8 +708,14 @@ export function createMailRoutes(deps) {
         }
         try {
             const updated = await registry.refreshImapSecret(accountId, serializeImapAccountSecret(secret), capabilities ?? undefined);
-            if (!updated)
-                return c.json({ error: "not_found" }, 404);
+            if (!updated) {
+                return respondWithAgentError(c, 404, [
+                    composeIssue("mail.account_not_found", {
+                        field: "accountId",
+                        received: c.req.param("id") ?? "<unknown>",
+                    }),
+                ]);
+            }
             return c.json({ status: "refreshed", account: updated });
         }
         catch (err) {
@@ -817,8 +974,14 @@ export function createMailRoutes(deps) {
     };
     app.get("/mail/:accountId/health", (c) => {
         const registry = deps.services.mail;
-        if (!registry)
-            return c.json({ error: "mail_not_configured" }, 503);
+        if (!registry) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
         const accountId = c.req.param("accountId");
         // §4.8 per-account mode gate — also applies to /health so the
         // dashboard does not surface a stale poll cursor for an account
@@ -839,8 +1002,14 @@ export function createMailRoutes(deps) {
             }
         }
         const health = registry.getHealth(accountId);
-        if (!health)
-            return c.json({ error: "not_found" }, 404);
+        if (!health) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("mail.account_not_found", {
+                    field: "accountId",
+                    received: accountId,
+                }),
+            ]);
+        }
         return c.json(health);
     });
     app.get("/mail/:accountId/messages", async (c) => {
@@ -991,7 +1160,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "untrash")) {
-            return c.json({ error: "not_implemented", message: `untrash not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "untrash", resolved.provider.kind);
         }
         try {
             await resolved.provider.untrash(messageId);
@@ -1009,7 +1178,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "archive")) {
-            return c.json({ error: "not_implemented", message: `archive not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "archive", resolved.provider.kind);
         }
         try {
             await resolved.provider.archive(messageId);
@@ -1080,7 +1249,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "getThread")) {
-            return c.json({ error: "not_implemented", message: `getThread not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "getThread", resolved.provider.kind);
         }
         const bodyMode = parseBodyMode(c.req.query("body"));
         if (!bodyMode.ok)
@@ -1100,7 +1269,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "listDrafts")) {
-            return c.json({ error: "not_implemented", message: `listDrafts not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "listDrafts", resolved.provider.kind);
         }
         const limit = parseIntParam(c.req.query("limit"), 20, { min: 1, max: 100 });
         try {
@@ -1116,7 +1285,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "getDraft")) {
-            return c.json({ error: "not_implemented", message: `getDraft not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "getDraft", resolved.provider.kind);
         }
         try {
             const draft = await resolved.provider.getDraft(c.req.param("draftId"));
@@ -1137,7 +1306,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "createDraft")) {
-            return c.json({ error: "not_implemented", message: `createDraft not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "createDraft", resolved.provider.kind);
         }
         const input = validateSendInput(parsedBody.body);
         if (!input.ok)
@@ -1158,7 +1327,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "updateDraft")) {
-            return c.json({ error: "not_implemented", message: `updateDraft not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "updateDraft", resolved.provider.kind);
         }
         const parsedBody = await readJsonBody(c);
         if (!parsedBody.ok)
@@ -1192,7 +1361,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "deleteDraft")) {
-            return c.json({ error: "not_implemented", message: `deleteDraft not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "deleteDraft", resolved.provider.kind);
         }
         try {
             await resolved.provider.deleteDraft(draftId);
@@ -1210,7 +1379,7 @@ export function createMailRoutes(deps) {
         if (!resolved.ok)
             return renderResolveError(c, resolved);
         if (!ensureMethod(resolved.provider, "sendDraft")) {
-            return c.json({ error: "not_implemented", message: `sendDraft not supported on ${resolved.provider.kind}` }, 501);
+            return notImplementedResponse(c, "sendDraft", resolved.provider.kind);
         }
         try {
             const result = await resolved.provider.sendDraft(draftId);
@@ -1356,20 +1525,43 @@ function providerError(c, err, tag) {
         pickNumber(candidate.statusCode) ??
         pickNumber(candidate.response?.status);
     if (status === 404) {
-        return c.json({ error: "not_found", message }, 404);
+        return respondWithAgentError(c, 404, [
+            composeIssue("mail.account_not_found", {
+                field: tag,
+                received: message,
+                hint: `Provider returned 404 for ${tag}. The resource (message, thread, label, draft) may have been deleted or the id is wrong. Re-fetch to verify.`,
+            }),
+        ], { legacyFields: { message } });
     }
     if (status === 501) {
         // Providers throw MailOperationNotSupportedError (httpStatus=501) when a
         // sub-case of an implemented method is out of scope — e.g. IMAP draft
         // writes. Map to the same shape as the missing-method-on-interface path
         // so callers can't distinguish the two (both mean "don't retry here").
-        return c.json({ error: "not_implemented", message }, 501);
+        return respondWithAgentError(c, 501, [
+            composeIssue("mail.not_implemented", {
+                field: tag,
+                received: message,
+                hint: `Provider returned 501 for ${tag} — operation outside the implemented sub-case. Stop retrying; either try a different operation or pick a different provider.`,
+            }),
+        ], { legacyFields: { message } });
     }
     if (status === 401 || status === 403) {
-        return c.json({ error: "provider_auth_error", message }, 502);
+        return respondWithAgentError(c, 502, [
+            composeIssue("mail.provider_auth_error", {
+                field: tag,
+                received: message,
+            }),
+        ], { legacyFields: { message } });
     }
     logger.error({ err, tag }, `mail route failure: ${tag}`);
-    return c.json({ error: tag, message }, 500);
+    return respondWithAgentError(c, 500, [
+        composeIssue("mail.upstream_error", {
+            field: tag,
+            received: message,
+            hint: `Mail provider ${tag} failed. Read the message verbatim. Transient 5xx may resolve after 30s; otherwise notify the user.`,
+        }),
+    ], { legacyErrorCode: tag, legacyFields: { message } });
 }
 function pickNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : null;