@sendinel/mcp-server 1.0.145 → 1.0.147

package/build/tools/contacts.js

@@ -1,4 +1,4 @@
-import { dbErrorResult } from '../lib/db-errors.js';
+import { normalizeTagInput, tagInputWarnings } from '../lib/tags.js';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CONTACT_ENRICHMENT_PROVIDERS } from '@desler/models';
 import { createContactEnrichmentAdapters, enrichContactFromConnections, } from '@desler/models/contact-enrichment';
@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { callSendinelV1 } from '../lib/v1-client.js';
 import { db, projectClientForWriteback } from '../db.js';
 import { getProjectId } from '../project.js';
-import { dbToolError, toolError } from '../lib/db-error.js';
+import { dbErrorResult, dbToolError, toolError } from '../lib/db-error.js';
 import { resolveSegmentContactIds } from '../lib/send-audience.js';
 import { checkPlanLimit, contactLimitMessage } from '../plan-limits.js';
 import { logConsent, logAudit } from '../audit.js';
@@ -335,7 +335,7 @@ async function resolveSubscriberViewSiteId(projectId, siteParam) {
         .eq('active', true)
         .order('name');
     if (error)
-        return { error: error.message };
+        return { ...dbToolError(error) };
     const all = (sites ?? []);
     if (SUBSCRIBER_VIEW_UUID_RE.test(siteParam)) {
         return { siteId: all.some((site) => site.id === siteParam) ? siteParam : undefined };
@@ -425,7 +425,7 @@ function isMissingRelationshipError(error) {
         return false;
     if (error.code === 'PGRST200')
         return true;
-    return /could not find a relationship/i.test(error.message ?? '');
+    return /could not find a relationship/i.test((error ? dbToolError(error).error : undefined) ?? '');
 }
 async function hasCompaniesEmbed(projectId) {
     const cached = companiesEmbedCache.get(projectId);
@@ -574,7 +574,7 @@ async function exportSubscriberData(projectId, contactId) {
         .eq('project_id', projectId)
         .maybeSingle();
     if (contactError)
-        return { error: contactError.message };
+        return { ...dbToolError(contactError) };
     if (!contact)
         return { error: 'Subscriber not found', code: 'NOT_FOUND' };
     const { data: emailHistory, error: logError } = await db()
@@ -585,7 +585,7 @@ async function exportSubscriberData(projectId, contactId) {
         .not('to_email', 'like', 'sha256:%')
         .order('sent_at', { ascending: false });
     if (logError)
-        return { error: logError.message };
+        return { ...dbToolError(logError) };
     const { data: suppression, error: suppressionError } = await db()
         .from('suppressions')
         .select('reason, created_at')
@@ -594,7 +594,7 @@ async function exportSubscriberData(projectId, contactId) {
         .not('email', 'like', 'sha256:%')
         .maybeSingle();
     if (suppressionError)
-        return { error: suppressionError.message };
+        return { ...dbToolError(suppressionError) };
     return {
         contact: {
             id: contact.id,
@@ -713,7 +713,7 @@ export function registerContactTools(server) {
     }, async () => {
         const { data, error } = await db().from('hygiene_config').select('*').eq('project_id', getProjectId()).maybeSingle();
         if (error)
-            return j({ error: error.message });
+            return j(dbToolError(error));
         return j(data ?? { enabled: false, inactive_days: 90, action: 'tag', tag_name: 'cold', suppress_after_days: 180, activity_property: null, last_run_at: null });
     });
     server.registerTool('update_hygiene_config', {
@@ -746,7 +746,7 @@ export function registerContactTools(server) {
             row.activity_property = activityProperty;
         const { error } = await db().from('hygiene_config').upsert(row, { onConflict: 'project_id' });
         if (error)
-            return j({ error: error.message });
+            return j(dbToolError(error));
         return j({ updated: true });
     });
     server.registerTool('run_list_hygiene', {
@@ -766,7 +766,7 @@ export function registerContactTools(server) {
         // read past 1000 is now safe as a follow-up.
         const { data: contacts, error: readError } = await db().from('subscribers').select('id, email, first_name, last_name, custom_properties, tags, last_engaged_at').eq('project_id', projectId).lt('last_engaged_at', cutoff).limit(1000);
         if (readError)
-            return j({ error: readError.message });
+            return j(dbToolError(readError));
         let tagged = 0;
         let skipped = 0;
         let failed = 0;
@@ -907,7 +907,7 @@ export function registerContactTools(server) {
             q = q.contains('tags', [`segment:${segmentId}`]);
         const { data: sample, error } = await q;
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         const apiKey = process.env.ANTHROPIC_API_KEY;
         if (!apiKey)
             return j({ error: 'ANTHROPIC_API_KEY not configured', code: 'AI_UNAVAILABLE' });
@@ -983,7 +983,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .eq('project_id', projectId)
                 .maybeSingle();
             if (viewError)
-                return txt(`Error: ${viewError.message}`);
+                return txt(`Error: ${dbToolError(viewError).error}`);
             if (!view)
                 return txt('Error: View not found');
             viewFilters = normalizeSubscriberViewFilters(view.filters);
@@ -1049,7 +1049,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .select('contact_id, subscribed')
                 .eq('site_id', statusSiteId);
             if (siteSubscriptionsError)
-                return txt(`Error: ${siteSubscriptionsError.message}`);
+                return txt(`Error: ${dbToolError(siteSubscriptionsError).error}`);
             if (viewStatus === 'not_subscribed') {
                 const subscribedIds = (siteSubscriptions ?? [])
                     .map((subscription) => subscription.contact_id)
@@ -1081,7 +1081,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         }
         const { data, error } = await q;
         if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+            return { content: [{ type: 'text', text: `Error: ${dbToolError(error).error}` }] };
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('list_subscriber_views', {
@@ -1101,7 +1101,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .eq('project_id', getProjectId())
             .order('created_at', { ascending: true });
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         return j({ views: data ?? [] });
     });
     server.registerTool('create_subscriber_view', {
@@ -1219,7 +1219,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .select('id')
             .maybeSingle();
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (!data)
             return txt('View not found');
         return j({ deleted: true, view_id });
@@ -1250,7 +1250,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         }
         const { data: companies, error } = await query;
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         const rows = companies ?? [];
         if (!rows.length)
             return j([]);
@@ -1265,7 +1265,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .order('id')
                 .range(offset, offset + 999);
             if (subscriberError)
-                return txt(`Error: ${subscriberError.message}`);
+                return txt(`Error: ${dbToolError(subscriberError).error}`);
             for (const subscriber of subscribers ?? []) {
                 const companyId = typeof subscriber.company_id === 'string' ? subscriber.company_id : null;
                 if (!companyId)
@@ -1299,6 +1299,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             company_id: z.string().uuid().optional(),
             company_name: z.string().optional(),
             company_domain: z.string().optional(),
+            tags: z.array(z.string()).optional().describe('Initial tags for new subscribers; existing contacts keep their stored tags.'),
             source: z.enum(['signup', 'import', 'form', 'manual']).optional().default('manual'),
             utm_source: z.string().optional(),
             utm_medium: z.string().optional(),
@@ -1306,8 +1307,11 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             utm_content: z.string().optional(),
             utm_term: z.string().optional(),
         },
-    }, async ({ email, site_id, first_name, last_name, company_id, company_name, company_domain, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
+    }, async ({ email, site_id, first_name, last_name, company_id, company_name, company_domain, tags, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
         try {
+            const normalizedTags = normalizeTagInput(tags ?? []);
+            const warnings = tagInputWarnings(normalizedTags);
+            const tagWarnings = warnings.length ? { warnings } : {};
             email = email.trim().toLowerCase();
             const projectId = getProjectId();
             // Block distribution list / system addresses
@@ -1351,6 +1355,8 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             let contact;
             if (!existingContact) {
                 const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
+                if (tags !== undefined)
+                    row.tags = normalizedTags.tags;
                 if (customProperties)
                     row.custom_properties = customProperties;
                 if (!needsConfirm)
@@ -1426,15 +1432,15 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             if (needsConfirm) {
                 // Create opt-in token (confirmation email must be sent externally in MCP context)
                 await db().from('opt_in_tokens').insert({ contact_id: contact.id, site_id });
-                await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
+                await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null, ...(!existing && tags !== undefined ? { tags: normalizedTags.tags } : {}) });
                 logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_pending_double_opt_in' });
-                return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
+                return { content: [{ type: 'text', text: JSON.stringify({ ...contact, ...tagWarnings, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
             }
-            await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
+            await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null, ...(!existing && tags !== undefined ? { tags: normalizedTags.tags } : {}) });
             logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
             if (!existing)
                 logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
-            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, ...existingMessage }, null, 2) }] };
+            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, ...tagWarnings, existing, ...existingMessage }, null, 2) }] };
         }
         catch (error) {
             return dbErrorResult(error);
@@ -1524,7 +1530,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .upsert(rows, { onConflict: 'project_id,email', ignoreDuplicates: false })
             .select('id, email, first_name, last_name, custom_properties');
         if (uErr)
-            return { content: [{ type: 'text', text: `Error: ${uErr.message}` }] };
+            return { content: [{ type: 'text', text: `Error: ${dbToolError(uErr).error}` }] };
         const contactRows = upserted ?? [];
         const subRows = contactRows.map((c) => ({ contact_id: c.id, site_id, subscribed: true }));
         if (subRows.length) {
@@ -1557,7 +1563,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .select('id, email, first_name, last_name, custom_properties')
             .single();
         if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+            return { content: [{ type: 'text', text: `Error: ${dbToolError(error).error}` }] };
         if (data) {
             // Cascade to site subscriptions
             await db()
@@ -1630,7 +1636,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             q = q.ilike('subject', `%${subject_contains.replace(/[\\%_]/g, (c) => `\\${c}`)}%`);
         const { data, error } = await q;
         if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+            return { content: [{ type: 'text', text: `Error: ${dbToolError(error).error}` }] };
         const fetched = (data ?? []);
         const hasMore = fetched.length > pageSize;
         // source: where the email came from. A campaign id wins; otherwise the stored category (transactional, test, marketing).
@@ -1665,7 +1671,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             q = q.eq('reason', reason);
         const { data, error } = await q;
         if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+            return { content: [{ type: 'text', text: `Error: ${dbToolError(error).error}` }] };
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('add_suppression', {
@@ -1689,7 +1695,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .select()
             .single();
         if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+            return { content: [{ type: 'text', text: `Error: ${dbToolError(error).error}` }] };
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('list_subscribers_by_segment', {
@@ -1728,7 +1734,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 segmentIds = await resolveSegmentContactIds(projectId, segment.rules);
             }
             catch (error) {
-                return toolError(isSegmentRulesError(error) ? { error: error.message, code: 'validation_failed' } : { error: 'Unable to evaluate segment', code: 'internal_error' });
+                return toolError(isSegmentRulesError(error) ? { ...dbToolError(error), code: 'validation_failed' } : { error: 'Unable to evaluate segment', code: 'internal_error' });
             }
             if (!segmentIds.length)
                 return j([]);
@@ -1815,6 +1821,9 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
     }, async ({ contact_id, email, first_name, last_name, company_id, company_name, company_domain, tags, custom_properties, phone_e164, timezone }) => {
         try {
             const projectId = getProjectId();
+            const normalizedTags = tags !== undefined ? normalizeTagInput(tags) : undefined;
+            if (normalizedTags)
+                tags = normalizedTags.tags;
             let propertyWarnings = [];
             let fields;
             if (custom_properties !== undefined) {
@@ -2000,7 +2009,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 ...(updates.tags !== undefined ? { tags: updates.tags } : {}),
                 ...(updates.custom_properties !== undefined ? { custom_properties: updates.custom_properties } : {}),
             });
-            const mergedWarnings = [...(tagResult.warnings ?? []), ...propertyWarnings];
+            const mergedWarnings = [...(tagResult.warnings ?? []), ...propertyWarnings, ...(normalizedTags ? tagInputWarnings(normalizedTags) : [])];
             return j({ ...data, ...tagResult, ...(mergedWarnings.length ? { warnings: mergedWarnings } : {}) });
         }
         catch (error) {
@@ -2035,7 +2044,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             return txt('Provide either contact_id or email.');
         const { data, error } = await q.maybeSingle();
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         return j(data);
     });
     server.registerTool('enrich_subscriber', {
@@ -2061,7 +2070,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .eq('id', contact_id)
             .maybeSingle();
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (!contact?.email)
             return j({ error: 'Subscriber not found', code: 'NOT_FOUND' });
         const enriched = await enrichContactFromProviders(projectId, contact.email, provider);
@@ -2099,7 +2108,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .select(embedOk ? '*, company:companies(id, name, domain)' : '*')
             .single();
         if (updateError)
-            return txt(`Error: ${updateError.message}`);
+            return txt(`Error: ${dbToolError(updateError).error}`);
         const appliedFields = [];
         if (!contact.first_name && enriched.firstName)
             appliedFields.push('first_name');
@@ -2136,57 +2145,78 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Add or remove tags from one or more contacts',
+        description: 'Add or remove tags from one or more contacts. Tags are trimmed; empty values are ignored; case variants of an existing tag are not added again. Removal is case-insensitive. Ids not found are returned in not_found.',
         inputSchema: {
             contact_ids: z.array(z.string().uuid()).min(1),
             add_tags: z.array(z.string()).optional(),
             remove_tags: z.array(z.string()).optional(),
         },
     }, async ({ contact_ids, add_tags = [], remove_tags = [] }) => {
+        const normalized = normalizeTagInput(add_tags);
+        add_tags = normalized.tags;
+        remove_tags = remove_tags.map(tag => tag.trim()).filter(Boolean);
+        const warnings = new Set(tagInputWarnings(normalized));
         if (!add_tags.length && !remove_tags.length)
             return toolError({ error: 'No tags to add or remove.', code: 'validation_failed' });
         const projectId = getProjectId();
         let updated = 0;
         const missing_contact_ids = [];
+        const failed = [];
         for (const cid of contact_ids) {
-            const { data: contact, error: readError } = await db()
-                .from('subscribers')
-                .select('id, email, first_name, last_name, custom_properties, tags')
-                .eq('id', cid)
-                .eq('project_id', projectId)
-                .maybeSingle();
-            if (readError)
-                return toolError({ ...dbToolError(readError), updated });
-            if (!contact) {
-                missing_contact_ids.push(cid);
-                continue;
-            }
-            const currentTags = contact.tags ?? [];
-            const removeSet = new Set(remove_tags);
-            const merged = currentTags.filter((t) => !removeSet.has(t));
-            for (const t of add_tags) {
-                if (!merged.includes(t))
-                    merged.push(t);
+            try {
+                const { data: contact, error: readError } = await db()
+                    .from('subscribers')
+                    .select('id, email, first_name, last_name, custom_properties, tags')
+                    .eq('id', cid)
+                    .eq('project_id', projectId)
+                    .maybeSingle();
+                if (readError) {
+                    failed.push({ id: cid, ...dbToolError(readError) });
+                    continue;
+                }
+                if (!contact) {
+                    missing_contact_ids.push(cid);
+                    continue;
+                }
+                const currentTags = contact.tags ?? [];
+                const removeSet = new Set(remove_tags.map(tag => tag.toLowerCase()));
+                const merged = currentTags.filter((t) => !removeSet.has(t.trim().toLowerCase()));
+                for (const tag of add_tags) {
+                    const existing = merged.find(value => value.trim().toLowerCase() === tag.toLowerCase());
+                    if (existing !== undefined)
+                        warnings.add(`${tag} already exists as ${existing}`);
+                    else
+                        merged.push(tag);
+                }
+                const { data: saved, error } = await db()
+                    .from('subscribers')
+                    .update({ tags: merged })
+                    .eq('id', cid)
+                    .eq('project_id', projectId)
+                    .select('id').maybeSingle();
+                if (error) {
+                    failed.push({ id: cid, ...dbToolError(error) });
+                    continue;
+                }
+                if (!saved) {
+                    missing_contact_ids.push(cid);
+                    continue;
+                }
+                updated++;
+                await writeBackMcpContact(projectId, contact, { tags: merged });
+                await logAudit({ action: 'subscriber.tags_updated', resourceType: 'subscriber', resourceId: cid, details: { add_tags, remove_tags } });
             }
-            const { data: saved, error } = await db()
-                .from('subscribers')
-                .update({ tags: merged })
-                .eq('id', cid)
-                .eq('project_id', projectId)
-                .select('id').maybeSingle();
-            if (error)
-                return toolError({ ...dbToolError(error), updated });
-            if (!saved) {
-                missing_contact_ids.push(cid);
-                continue;
+            catch {
+                failed.push({ id: cid, ...dbToolError({}) });
             }
-            updated++;
-            await writeBackMcpContact(projectId, contact, { tags: merged });
-            await logAudit({ action: 'subscriber.tags_updated', resourceType: 'subscriber', resourceId: cid, details: { add_tags, remove_tags } });
         }
+        const result = { missing_contact_ids, not_found: missing_contact_ids, failed, updated, total: contact_ids.length, add_tags, remove_tags, ...(warnings.size ? { warnings: [...warnings] } : {}) };
+        // Preserve the existing coded-error convention when no requested write succeeded.
+        if (!updated && failed.length)
+            return toolError({ ...dbToolError({}), ...result, code: failed[0].code, error: failed[0].error });
         if (!updated)
-            return toolError({ error: 'Subscriber not found', code: 'not_found', updated, missing_contact_ids });
-        return j({ missing_contact_ids, updated, total: contact_ids.length, add_tags, remove_tags });
+            return toolError({ error: 'Subscriber not found', code: 'not_found', ...result });
+        return j(result);
     });
     server.registerTool('bulk_update_subscribers', {
         title: 'Bulk Update Subscribers',
@@ -2324,7 +2354,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             }
             catch (error) {
                 if (isSegmentRulesError(error))
-                    return txt(`Error: ${error.message}`);
+                    return txt(`Error: ${dbToolError(error).error}`);
                 throw error;
             }
         }
@@ -2349,7 +2379,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         }
         const { data, error } = await q.order('engagement_score', { ascending: false }).limit(sampleSize);
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         // Get full count separately
         let countQ = db()
             .from('subscribers')
@@ -2435,7 +2465,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .order('email')
                 .range(offset, offset + 999);
             if (suppressionError)
-                return txt(`Error: ${suppressionError.message}`);
+                return txt(`Error: ${dbToolError(suppressionError).error}`);
             for (const suppression of suppressed ?? [])
                 suppressedSet.add(suppression.email);
             if ((suppressed ?? []).length < 1000)
@@ -2443,7 +2473,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         }
         const { data: contacts, error } = await q.order('engagement_score', { ascending: true }).limit(sampleLimit);
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         const inactive = (contacts ?? []).filter((c) => !suppressedSet.has(c.email));
         if (!dry_run && inactive.length > 0) {
             const channelContext = currentChannelContext();
@@ -2475,7 +2505,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .from('suppressions')
                 .upsert(suppressionRows, { onConflict: 'project_id,email', ignoreDuplicates: true });
             if (supErr)
-                return txt(`Error suppressing: ${supErr.message}`);
+                return txt(`Error suppressing: ${dbToolError(supErr).error}`);
             return j({ suppressed: inactive.length, days_threshold: days, sample: inactive });
         }
         return j({
@@ -2511,7 +2541,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .select()
             .single();
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (!data)
             return txt(`No suppression found for ${email}.`);
         return j({ removed: true, email, previous_reason: data.reason });
@@ -2594,7 +2624,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             for (const ids of chunkIds(siteIds)) {
                 const part = await scanChunk(ids);
                 if (!part.ok)
-                    return txt(`Error: ${part.error.message}`);
+                    return txt(`Error: ${dbToolError(part.error).error}`);
                 all.push(...part.rows);
                 total = total === null || part.total === null ? null : total + part.total;
             }
@@ -2606,7 +2636,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             scan = await scanChunk(siteIds);
         }
         if (!scan.ok)
-            return txt(`Error: ${scan.error.message}`);
+            return txt(`Error: ${dbToolError(scan.error).error}`);
         const contacts = scan.rows;
         // #3604: say when the scan stopped at the limit instead of presenting a partial scan as complete.
         const scanned = contacts?.length ?? 0;
@@ -2682,7 +2712,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             p_source_ids: source_ids,
         });
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         logAudit({ action: 'contacts.merged', resourceType: 'contact', resourceId: target_id, details: { source_ids, result: data } });
         return j(data);
     });
@@ -2706,7 +2736,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 ...(siteScope ? { p_site_id: siteScope } : {}),
             });
             if (error)
-                return { error: `Error: ${error.message}` };
+                return { error: `Error: ${dbToolError(error).error}` };
             const result = (Array.isArray(data) ? data[0] : data);
             if (typeof result?.has_membership !== 'boolean' || !Array.isArray(result.keys)) {
                 return { error: 'Error: get_contact_schema_keys returned an unreadable result' };
@@ -2811,7 +2841,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         if (error) {
             if (error.code === '23505')
                 return contactInputError('conflict', `Error: A custom field with key "${key}" already exists.`);
-            return j({ error: `Error: ${error.message}`, code: 'INTERNAL_ERROR' });
+            return j({ error: `Error: ${dbToolError(error).error}`, code: 'INTERNAL_ERROR' });
         }
         await logAudit({
             action: 'custom_field.created',
@@ -2842,7 +2872,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .eq('project_id', projectId)
             .maybeSingle();
         if (currentError)
-            return txt(`Error: ${currentError.message}`);
+            return txt(`Error: ${dbToolError(currentError).error}`);
         if (!current)
             return j({ error: 'Custom field not found', code: 'NOT_FOUND' });
         const nextType = (type ?? current.type);
@@ -2868,7 +2898,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .select('id, key, label, type, required, options, display_order')
             .maybeSingle();
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (!data)
             return j({ error: 'Custom field not found', code: 'NOT_FOUND' });
         await logAudit({
@@ -2894,7 +2924,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .select('id, key')
             .maybeSingle();
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (!data)
             return j({ error: 'Custom field not found', code: 'NOT_FOUND' });
         await logAudit({
@@ -2921,7 +2951,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
     }, async ({ contact_id, window_hours }) => {
         const { data, error } = await getContactNeighborhood(db(), getProjectId(), contact_id, window_hours);
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (data == null)
             return j({ error: 'Subscriber not found', code: 'NOT_FOUND' });
         return j({ ...data, attention: buildPreviewAttentionEnvelope() });
@@ -2942,7 +2972,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
     }, async ({ contact_id, window_hours }) => {
         const { data, error } = await getScheduledTouches(db(), getProjectId(), contact_id, window_hours);
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (data == null)
             return j({ error: 'Subscriber not found', code: 'NOT_FOUND' });
         return j({ ...data, attention: buildPreviewAttentionEnvelope() });
@@ -2969,7 +2999,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             enrollmentId: enrollment_id,
         });
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (data == null)
             return j({ error: 'Not found', code: 'NOT_FOUND' });
         return j(data);
@@ -2994,7 +3024,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             }
             const { data, error } = await getContactNeighborhood(db(), getProjectId(), contactId);
             const payload = error
-                ? { error: error.message }
+                ? { ...dbToolError(error) }
                 : data == null
                     ? { error: 'Subscriber not found', code: 'NOT_FOUND' }
                     : data;