@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/server/email-send.js

@@ -0,0 +1,667 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { buildCrmEmailActivity, contactCaptureHostIds, CRM_ACTIVITY_LOG_FULL_MESSAGE, CRM_COLLECTIONS, CRM_EMAIL_BODY_MAX, CRM_EMAIL_CONTEXT, CRM_EMAIL_SUBJECT_MAX, crmActivityLogHasRoom, crmEmailDeliveryTags, crmMergeFieldsIn, crmScopeTokens, isOrgWideMember, normalizeContactEmail, readContactFacet, readMarketingBasis, renderCrmMergeFields, resolveOrgEntitlements, visibleToHost } from "@aglyn/aglyn/server";
+import { isEmailConfigured, sendEmail, sendFailureReason } from "@aglyn/shared-util-email";
+import { consentGroupForSite, consumeRateLimit, countCrmActivitiesForRecord, filterSendableForHost, firebaseAdmin, getHostDocAdmin, getOrgForHost, hostSendingIdentity, logOrgActivity, memberHasOrgPermission, newCrmActivityRef, orgDataCollectionForHost, readOrgEmailRamp, recordEmailSends, releaseCrmEmailSend, reserveCrmEmailSend, resolveOrgMembership, writeCrmEmailActivity } from "@aglyn/tenant-data-admin";
+import { isRefusedIdToken } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { authorizeOrgCaller, orgHostIds, readCrmRouteScope } from "./org-caller.js";
+import { crmSuiteRefusal } from "./suite-gate.js";
+/**
+ * `POST /api/crm/email-send` — one email to one person, from their record
+ * (AGL-2615).
+ *
+ * Body: `{ hostId, contactId? | leadId? | dealId?, subject, body }`. Answers
+ * `{ ok: true, activityId, to, from, logged }` once the provider accepted
+ * the message, and a refusal with a `reason` the dialog can act on
+ * otherwise. The subject and the body may carry merge fields —
+ * `{{contact.firstName}}`, `{{deal.amount}}` (AGL-2658) — which this route
+ * fills from the record before the send, so the timeline row is the letter
+ * as it left; see `crm-email-templates.ts` for the grammar.
+ *
+ * ## What it is, and what it is not
+ *
+ * A message a teammate wrote to one person they have a relationship with —
+ * a reply to a lead, a follow-up on a deal. It is not marketing: no
+ * campaign audience, no unsubscribe pair, no frequency window, no consent
+ * split. What it does owe is everything a bounce or a complaint owes the
+ * shared sending domain, which is why BOTH suppression lists are consulted
+ * and why a person's own stated refusal — a `declined` basis — is a hard
+ * stop even though the message is not the kind of mail that basis governs.
+ * The recipient asked this site not to write; the kind of writing is not
+ * the point.
+ *
+ * ## Why the recipient is resolved here and not taken from the body
+ *
+ * The dialog shows the address the record carries, and this route reads it
+ * again off the record the caller named, through the same visibility check
+ * every other CRM route makes. A `to` in the body would make this a route
+ * that sends the site's mail to any address a member types, which is a
+ * different product with a different abuse surface.
+ *
+ * ## The organization variant (AGL-2634)
+ *
+ * `{ orgId, hostId?, … }` from the org-level hub. The caller is authorized
+ * by the org — an org-wide member holding `data.manage` — and the record is
+ * read with no site's visibility to check, because an org-wide member reads
+ * every row. What the org level cannot do away with is the SITE the message
+ * leaves from: the sending identity, the suppression list and the person's
+ * stated refusal are each a site's. So the org variant still names one —
+ * the record's own capturing site or the site the reader picked, in the
+ * body; failing that the record's own site read off the document; failing
+ * that the org's only site — and refuses, with a `site` reason, when the
+ * org has several and none was named. The row it writes is visible to
+ * whoever may see the RECORD, so an email to a person another site
+ * captured shows on their timeline under that site's hub; the act is
+ * logged in the org's feed.
+ *
+ * ## The order of the gates
+ *
+ * Cheap and certain first. A malformed body and a missing token cost
+ * nothing; the per-user pace is one counter; the record is one read and
+ * decides everything after it; the ceiling one aggregate; the two
+ * suppression lists two keyed reads; the sending identity next, because it
+ * is the most expensive and the one a workspace fixes once. The daily cap
+ * comes LAST and is the one gate that writes before the provider is called
+ * (AGL-2645): the send is reserved on today's counter inside a transaction,
+ * so two reps at the last slot cannot both pass one reading of it, and a
+ * message the provider refuses gives the slot back. After the provider has
+ * accepted, two more things are written, neither able to fail the send:
+ * the activity row and the org's cost meter.
+ *
+ * ## The new-workspace ramp is part of that cap, not a gate beside it
+ *
+ * A message from a workspace created this morning lands on the sending
+ * domain every other tenant's receipts leave on, so the plan's day is held
+ * to the share of it the workspace has earned — the same ramp the campaign
+ * path is paced by, `readOrgEmailRamp`, taken to the allowance this surface
+ * meters instead of the campaign ceiling. It is handed to the reservation
+ * rather than checked before it, so the ceiling and the count it is judged
+ * against come out of the one transactional read; a ramp consulted
+ * separately would be a second ceiling and two reps could pass it at once.
+ * A workspace past its first week is not ramped and pays nothing to find
+ * that out.
+ */ /** How many one-to-one emails one person may send in one minute. */ export const CRM_EMAIL_SENDS_PER_MINUTE = 20;
+const CRM_EMAIL_RATE_WINDOW_MS = 60000;
+/** What the route says when the plan carries no one-to-one email at all. */ export const CRM_EMAIL_NOT_INCLUDED_MESSAGE = 'Your plan does not include one-to-one email. Upgrade in Billing to email ' + 'people from their records.';
+/** What the route says at the daily cap; `included` is the plan's figure. */ export function crmEmailCapReachedMessage(included) {
+    return `Today's one-to-one email limit (${included.toLocaleString('en-US')}) is ` + 'reached. It resets at midnight UTC — see Billing for the count.';
+}
+/**
+ * What the route says when the NEW-WORKSPACE RAMP is the ceiling that was
+ * reached, rather than the plan's own.
+ *
+ * The campaign path's wording, pointed at this surface: the number, what was
+ * spent against it, that nothing was sent or counted, and when it lifts. A
+ * workspace told only "limit reached" against a figure far below the one its
+ * plan page advertises would read it as a billing fault.
+ */ export function crmEmailRampReachedMessage(ceiling, used) {
+    return `This workspace may send ${ceiling.toLocaleString('en-US')} one-to-one ` + `email${ceiling === 1 ? '' : 's'} a day while it establishes a sending ` + `history, and has sent ${used.toLocaleString('en-US')} today. Nothing ` + 'has been sent and nothing has been counted — the allowance grows as ' + "the workspace sends, and is the plan's in full after its first week. " + 'It resets at midnight UTC.';
+}
+/** What the route says when the ramp's own history could not be read. */ export const CRM_EMAIL_RAMP_UNAVAILABLE_MESSAGE = "This workspace's sending history could not be read just now, so how much " + 'of its first-week email allowance it has earned is not known. Nothing has ' + 'been sent and nothing has been counted — try again in a moment.';
+export const CRM_EMAIL_SUPPRESSED_MESSAGE = 'This address has bounced or reported a message as spam, so it cannot be ' + 'emailed.';
+export const CRM_EMAIL_DECLINED_MESSAGE = 'This person asked not to be emailed by this site.';
+export const CRM_EMAIL_RATE_MESSAGE = 'You have sent too many emails in the last minute. Wait a moment and try again.';
+/** What the org variant says when no site was named and the org has several. */ export const CRM_EMAIL_PICK_SITE_MESSAGE = 'Pick the site this email leaves from — its sending address is what the ' + 'message is sent as.';
+const refuse = (status, error, extra = {})=>({
+        ok: false,
+        status,
+        body: _extends({
+            error
+        }, extra)
+    });
+/** One typed field, trimmed and bounded. */ function typed(value, max) {
+    return String(value != null ? value : '').trim().slice(0, max);
+}
+/**
+ * Who is sending, and whether they may: a verified ID token, then
+ * `data.manage` on the site's org through the same three-layer read the
+ * create route makes, admitted only for a site the member reaches. Staff
+ * pass the permission check as they do on every CRM route, and send as
+ * themselves.
+ */ async function authorizeSender(req, hostId) {
+    var _req_headers_authorization, _resolved_org;
+    const authorization = String((_req_headers_authorization = req.headers.authorization) != null ? _req_headers_authorization : '');
+    const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+    if (!idToken) return refuse(401, 'Unauthenticated');
+    let decoded;
+    try {
+        decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+    } catch (error) {
+        // A refused credential is the caller's 401; a failure to check one is
+        // ours and keeps a 5xx (AGL-2852).
+        if (isRefusedIdToken(error)) return refuse(401, 'Unauthenticated');
+        console.error('[crm] email-send could not verify the sender', error);
+        return refuse(500, 'The sign-in could not be checked. Try again.');
+    }
+    const resolved = await getOrgForHost(hostId).catch(()=>null);
+    if (!resolved) return refuse(404, 'Unknown site');
+    const { orgId } = resolved;
+    const org = (_resolved_org = resolved.org) != null ? _resolved_org : {};
+    if (decoded.staff !== true) {
+        var _ref;
+        var _member_hostAccess;
+        const membership = await resolveOrgMembership(decoded.uid, orgId).catch(()=>null);
+        const member = (_ref = membership == null ? void 0 : membership.member) != null ? _ref : null;
+        const reaches = isOrgWideMember(member) || Boolean(member == null ? void 0 : (_member_hostAccess = member.hostAccess) == null ? void 0 : _member_hostAccess[hostId]);
+        const allowed = member && reaches && await memberHasOrgPermission(orgId, member, 'data.manage');
+        if (!allowed) {
+            return refuse(403, 'Sending email from a record requires the data.manage permission on this site');
+        }
+    }
+    const email = normalizeContactEmail(decoded.email);
+    if (!email) {
+        // A reply-to is owed and the token is the only place it can honestly
+        // come from; an account with no address cannot be replied to.
+        return refuse(403, 'Your account has no email address to receive replies at.');
+    }
+    return {
+        ok: true,
+        uid: decoded.uid,
+        email,
+        name: typed(decoded.name, 120),
+        orgId,
+        org
+    };
+}
+/**
+ * The org variant's sender (AGL-2634): authorized by the org for an
+ * org-wide member holding `data.manage`, with the same reply-to rule.
+ */ async function authorizeOrgSender(req, orgId) {
+    const caller = await authorizeOrgCaller(req, orgId, {
+        needs: 'data.manage',
+        refusal: 'Sending email at the organization level requires the data.manage ' + 'permission across the whole workspace'
+    });
+    if (caller.ok === false) return refuse(caller.status, caller.error);
+    const email = normalizeContactEmail(caller.email);
+    if (!email) {
+        return refuse(403, 'Your account has no email address to receive replies at.');
+    }
+    return {
+        ok: true,
+        uid: caller.uid,
+        email,
+        name: caller.name,
+        orgId,
+        org: caller.org
+    };
+}
+/**
+ * The person the named record is about, as THIS site may see them.
+ *
+ * A deal names its contact; a lead carries its own address; a contact is
+ * itself. Each is looked up by id and then checked against what the site
+ * may read — the Admin SDK evaluates no rules, and a member of site A must
+ * not be able to mail site B's contact by guessing an id. The links the
+ * activity is filed under are whatever resolved: a deal's email is also the
+ * contact's, so it lands on both timelines.
+ *
+ * At the organization level there is no site to check against and none is
+ * checked: the caller was admitted as an org-wide member, who reads every
+ * row. A lead still needs its site named — a lead lives under one.
+ */ async function resolveRecipient(firestore, scope, orgId, ids) {
+    const link = {};
+    const { hostId } = scope;
+    const scoped = scope.level === 'site';
+    const visible = (tokens)=>!scoped || visibleToHost(tokens, hostId);
+    let contactId = ids.contactId;
+    let siteHint = '';
+    let dealRecord = null;
+    if (ids.dealId) {
+        var _deal_data, _deal_get;
+        const deal = await firestore.collection('orgs').doc(orgId).collection(CRM_COLLECTIONS.deals).doc(ids.dealId).get();
+        if (!deal.exists || !visible(deal.get('visibleTo'))) {
+            return refuse(404, 'Unknown deal');
+        }
+        link.dealId = deal.id;
+        dealRecord = (_deal_data = deal.data()) != null ? _deal_data : {};
+        siteHint = typed(deal.get('hostId'), 128);
+        contactId = contactId || String((_deal_get = deal.get('contactId')) != null ? _deal_get : '').trim();
+        if (!contactId) {
+            return refuse(400, 'This deal names no contact to email.');
+        }
+    }
+    if (contactId) {
+        var _contact_data;
+        const contacts = scoped ? await orgDataCollectionForHost(hostId, 'contacts') : firestore.collection('orgs').doc(orgId).collection('contacts');
+        const contact = await contacts.doc(contactId).get();
+        if (!contact.exists || !visible(contact.get('visibleTo'))) {
+            return refuse(404, 'Unknown contact');
+        }
+        const email = normalizeContactEmail(contact.get('email'));
+        if (!email) return refuse(400, 'This contact has no email address.');
+        const record = (_contact_data = contact.data()) != null ? _contact_data : {};
+        link.contactId = contact.id;
+        if (ids.leadId) link.leadId = ids.leadId;
+        siteHint = siteHint || typed(record['hostId'], 128) || contactCaptureHostIds(record)[0] || '';
+        return {
+            ok: true,
+            email,
+            record,
+            contact: record,
+            link,
+            siteHint,
+            deal: dealRecord,
+            lead: null
+        };
+    }
+    if (ids.leadId) {
+        var _lead_data, _lead_get;
+        if (!hostId) return refuse(400, 'Name the site the lead lives under.');
+        const lead = await firestore.collection('hosts').doc(hostId).collection('leads').doc(ids.leadId).get();
+        if (!lead.exists) return refuse(404, 'Unknown lead');
+        const email = normalizeContactEmail(lead.get('email'));
+        if (!email) return refuse(400, 'This lead has no email address.');
+        const record = (_lead_data = lead.data()) != null ? _lead_data : {};
+        link.leadId = lead.id;
+        // A converted lead's email belongs on the contact it became as well.
+        const converted = String((_lead_get = lead.get('convertedContactId')) != null ? _lead_get : '').trim();
+        if (converted) link.contactId = converted;
+        return {
+            ok: true,
+            email,
+            record,
+            contact: null,
+            link,
+            siteHint: hostId,
+            deal: null,
+            lead: record
+        };
+    }
+    return refuse(400, 'Name a contact, lead or deal to email.');
+}
+/**
+ * The site an org-level send leaves from (AGL-2634): the body's, else the
+ * record's own, else the org's only site — and a refusal the dialog turns
+ * into a Site picker when the org has several and none was named.
+ */ async function resolveSendingSite(firestore, scope, orgId, siteHint) {
+    if (scope.hostId) return {
+        ok: true,
+        hostId: scope.hostId
+    };
+    if (siteHint) return {
+        ok: true,
+        hostId: siteHint
+    };
+    const hosts = await orgHostIds(firestore, orgId);
+    if (hosts.length === 1) return {
+        ok: true,
+        hostId: hosts[0]
+    };
+    return refuse(409, CRM_EMAIL_PICK_SITE_MESSAGE, {
+        reason: 'site'
+    });
+}
+/** The HTTP shape of a send the provider did not accept. */ function sendRefusal(result) {
+    var _result_detail;
+    const reason = sendFailureReason(result);
+    const detail = String((_result_detail = result.detail) != null ? _result_detail : '');
+    if (reason === 'unverified-domain') {
+        return refuse(409, detail || 'This site has no verified sending identity.', {
+            reason: 'sending-identity'
+        });
+    }
+    if (reason === 'suppressed' || reason === 'unengaged') {
+        return refuse(409, CRM_EMAIL_SUPPRESSED_MESSAGE, {
+            reason: 'suppressed'
+        });
+    }
+    if (reason === 'rate-limited') {
+        const retryAtMs = Number(result.retryAtMs);
+        return refuse(503, 'The mail provider asked us to slow down. Try again in a minute.', {
+            reason: 'provider-rate',
+            retryAfterSeconds: Number.isFinite(retryAtMs) ? Math.max(1, Math.ceil((retryAtMs - Date.now()) / 1000)) : 60
+        });
+    }
+    if (reason === 'unconfigured') {
+        return refuse(501, 'Email is not configured on this deployment.', {
+            reason: 'unconfigured'
+        });
+    }
+    return refuse(502, 'The email could not be sent.', {
+        reason: 'send-failed'
+    });
+}
+/** What the route says when a subject or a message is nothing once its fields are filled. */ export const CRM_EMAIL_EMPTY_AFTER_MERGE_MESSAGE = 'The subject and the message are empty once their merge fields are filled ' + 'in. Check the fields against this record.';
+/**
+ * What `{{…}}` reads from, for this send (AGL-2658): the documents already
+ * in hand — the contact, the deal, the lead — the sender off their token,
+ * and the site's name, read only when a field asks for it. The contact's
+ * facet is the SENDING site's group's, because a name, a job title and a
+ * company are one holder's knowledge of a person.
+ */ async function mergeContextFor(options) {
+    const { recipient, sender, hostId, groupId, fields } = options;
+    const wantsSite = fields.some((field)=>field.startsWith('site.'));
+    const host = wantsSite ? await getHostDocAdmin(hostId).catch(()=>null) : null;
+    return {
+        contact: recipient.contact,
+        contactGroupId: groupId,
+        lead: recipient.lead,
+        deal: recipient.deal,
+        sender: {
+            name: sender.name,
+            email: sender.email
+        },
+        site: {
+            name: typed(host == null ? void 0 : host['displayName'], 200)
+        }
+    };
+}
+function answer(res, refusal) {
+    const retry = refusal.body['retryAfterSeconds'];
+    if (typeof retry === 'number') res.setHeader('Retry-After', String(retry));
+    res.status(refusal.status).json(refusal.body);
+}
+export const crmEmailSendHandler = async (req, res)=>{
+    var _req_body, _body_body;
+    if (req.method !== 'POST') {
+        res.setHeader('Allow', 'POST');
+        res.status(405).json({
+            error: 'Method not allowed'
+        });
+        return;
+    }
+    const body = (_req_body = req.body) != null ? _req_body : {};
+    const routeScope = readCrmRouteScope(body);
+    if (!routeScope) {
+        res.status(400).json({
+            error: 'Missing hostId'
+        });
+        return;
+    }
+    const ids = {
+        contactId: typed(body['contactId'], 128),
+        leadId: typed(body['leadId'], 128),
+        dealId: typed(body['dealId'], 128)
+    };
+    if (!ids.contactId && !ids.leadId && !ids.dealId) {
+        res.status(400).json({
+            error: 'Name a contact, lead or deal to email.'
+        });
+        return;
+    }
+    const draftSubject = typed(body['subject'], CRM_EMAIL_SUBJECT_MAX);
+    if (!draftSubject) {
+        res.status(400).json({
+            error: 'Enter a subject.'
+        });
+        return;
+    }
+    // Paragraphs are what the dialog offers, and a plain-text part is what a
+    // paragraph is; line endings are normalized so the stored body and the
+    // sent body are one string.
+    const draftText = String((_body_body = body['body']) != null ? _body_body : '').replace(/\r\n?/g, '\n').trim().slice(0, CRM_EMAIL_BODY_MAX);
+    if (!draftText) {
+        res.status(400).json({
+            error: 'Write the message.'
+        });
+        return;
+    }
+    try {
+        const sender = routeScope.level === 'org' ? await authorizeOrgSender(req, routeScope.orgId) : await authorizeSender(req, routeScope.hostId);
+        if (sender.ok === false) return answer(res, sender);
+        const { orgId, org } = sender;
+        /*
+     * THE PLAN, before the pace and the cap (AGL-2787). One-to-one email is
+     * the suite's; a plan without the suite is refused as such, rather than
+     * reaching the daily cap and being told about a zero it has no way to
+     * raise short of the upgrade this names.
+     */ const suite = crmSuiteRefusal(org, 'Emailing one person from their record');
+        if (suite) return answer(res, {
+            ok: false,
+            status: suite.status,
+            body: suite.body
+        });
+        /*
+     * THE PER-USER PACE, on its own key. The console dispatcher already
+     * counts this write against the person's general console budget; this
+     * is the narrower bucket the feature owes — twenty a minute is a rep
+     * writing, and past it is a script — keyed by the uid the token proved
+     * so one person cannot spend the bucket of everyone on their address.
+     */ const rate = await consumeRateLimit(`crm-email-send:uid:${sender.uid}`, {
+            limit: CRM_EMAIL_SENDS_PER_MINUTE,
+            windowMs: CRM_EMAIL_RATE_WINDOW_MS
+        });
+        if (!rate.allowed) {
+            return answer(res, refuse(429, CRM_EMAIL_RATE_MESSAGE, {
+                reason: 'rate',
+                retryAfterSeconds: Math.max(1, Math.ceil((rate.resetMs - Date.now()) / 1000))
+            }));
+        }
+        const firestore = firebaseAdmin.app().firestore();
+        const recipient = await resolveRecipient(firestore, routeScope, orgId, ids);
+        if (recipient.ok === false) return answer(res, recipient);
+        // The site the message leaves from — the mounted one under a site, and
+        // at the organization level whatever the body, the record or the org
+        // can answer.
+        const site = await resolveSendingSite(firestore, routeScope, orgId, recipient.siteHint);
+        if (site.ok === false) return answer(res, site);
+        const { hostId } = site;
+        const group = await consentGroupForSite(hostId, org);
+        // The company the sending site files this person under, so the email
+        // shows on the company's log as the automation step's rows do.
+        if (recipient.contact) {
+            const facet = readContactFacet(recipient.contact, group.groupId);
+            if (facet.companyId) recipient.link.companyId = facet.companyId;
+        }
+        /*
+     * MERGE FIELDS (AGL-2658), filled here rather than in the dialog: the
+     * dialog previews with the same resolver, but what leaves and what is
+     * logged is rendered by the route, off the documents it read to find
+     * the recipient, so a preview the rep did not look at cannot differ
+     * from the letter. A subject or a message that is nothing once its
+     * fields are filled is refused before any gate is spent on it.
+     */ const fields = crmMergeFieldsIn(`${draftSubject}\n${draftText}`);
+        const merge = fields.length ? await mergeContextFor({
+            recipient,
+            sender,
+            hostId,
+            groupId: group.groupId,
+            fields
+        }) : null;
+        const subject = merge ? renderCrmMergeFields(draftSubject, merge).trim().slice(0, CRM_EMAIL_SUBJECT_MAX) : draftSubject;
+        const text = merge ? renderCrmMergeFields(draftText, merge).trim().slice(0, CRM_EMAIL_BODY_MAX) : draftText;
+        if (!subject || !text) {
+            return answer(res, refuse(400, CRM_EMAIL_EMPTY_AFTER_MERGE_MESSAGE, {
+                reason: 'merge'
+            }));
+        }
+        // The per-record ceiling, before the send: an email that could not be
+        // logged would be a message the timeline never shows, and the timeline
+        // is the reason the send lives on the record.
+        const orgRef = firestore.collection('orgs').doc(orgId);
+        if (!crmActivityLogHasRoom(await countCrmActivitiesForRecord(orgRef, recipient.link))) {
+            return answer(res, refuse(409, CRM_ACTIVITY_LOG_FULL_MESSAGE, {
+                reason: 'ceiling'
+            }));
+        }
+        // Both suppression lists, then the person's own refusal.
+        const sendable = await filterSendableForHost(hostId, [
+            recipient.email
+        ]);
+        if (!sendable.length) {
+            return answer(res, refuse(409, CRM_EMAIL_SUPPRESSED_MESSAGE, {
+                reason: 'suppressed'
+            }));
+        }
+        if (readMarketingBasis(recipient.record, group).basis === 'declined') {
+            return answer(res, refuse(409, CRM_EMAIL_DECLINED_MESSAGE, {
+                reason: 'declined'
+            }));
+        }
+        if (!isEmailConfigured()) {
+            return answer(res, refuse(501, 'Email is not configured on this deployment.', {
+                reason: 'unconfigured'
+            }));
+        }
+        const identity = await hostSendingIdentity(hostId);
+        if (identity.refusal) {
+            return answer(res, refuse(409, identity.refusal.message, {
+                reason: 'sending-identity'
+            }));
+        }
+        const now = new Date();
+        /*
+     * THE NEW-WORKSPACE RAMP, resolved for the ceiling below.
+     *
+     * A workspace past its first week graduates off the org record alone and
+     * pays no read for this. One that is still on the ramp needs its
+     * delivery history to know which step it has earned, and when that
+     * history is unreadable the step is a floor rather than an answer.
+     *
+     * A floor is enough for a campaign, which defers what it cannot send
+     * today and delivers it tomorrow. It is not enough here: this route
+     * admits or refuses ONE message and has no third answer, so a ramp that
+     * cannot say what a workspace has earned refuses and says so. The
+     * refusal is transient by construction — it lasts as long as the window
+     * read is failing — and it reaches only workspaces inside their first
+     * week, since every other one graduated before the window was consulted.
+     */ const { ramp, degraded } = await readOrgEmailRamp({
+            orgId,
+            createdAt: org['createdAt'],
+            now: now.getTime()
+        });
+        if (degraded) {
+            return answer(res, refuse(503, CRM_EMAIL_RAMP_UNAVAILABLE_MESSAGE, {
+                reason: 'ramp-unavailable'
+            }));
+        }
+        // THE DAILY CAP (AGL-2611), taken as a slot rather than read as a
+        // figure (AGL-2645): the transaction reads today's counter, judges it
+        // with `checkCrmEmailQuota` against the ramp's share of the plan's day
+        // and raises it in one step, so the count the cap enforces is the count
+        // this send was admitted on.
+        const claim = await reserveCrmEmailSend(firestore, orgId, org, now, ramp);
+        if (!claim.ok) {
+            const { quota } = claim;
+            // WHICH ceiling was reached, in the org's own terms. The reservation
+            // answers with the number it judged, which is the plan's day unless
+            // the ramp held this workspace below it — and a workspace shown a
+            // figure under the one its plan page advertises is owed the reason.
+            const rampBound = quota.included < resolveOrgEntitlements(org).crmEmailsPerDay;
+            return answer(res, refuse(409, quota.included <= 0 ? CRM_EMAIL_NOT_INCLUDED_MESSAGE : rampBound ? crmEmailRampReachedMessage(quota.included, quota.used) : crmEmailCapReachedMessage(quota.included), {
+                reason: rampBound ? 'ramp' : 'quota',
+                included: quota.included,
+                used: quota.used,
+                resetsAtMs: quota.resetsAt.getTime()
+            }));
+        }
+        // The row's id, minted before the send so the delivery webhook can find
+        // it from the tags alone; written only once the message has left.
+        const activityRef = newCrmActivityRef(firestore, orgId);
+        let result;
+        try {
+            result = await sendEmail(_extends({
+                to: recipient.email,
+                subject,
+                text,
+                sendingIdentity: identity,
+                audience: 'tenant',
+                context: CRM_EMAIL_CONTEXT,
+                replyTo: sender.email
+            }, sender.name ? {
+                fromName: sender.name
+            } : {}, {
+                tags: crmEmailDeliveryTags({
+                    orgId,
+                    hostId,
+                    activityId: activityRef.id
+                })
+            }));
+        } catch (error) {
+            // The provider never answered, so no message left: the slot goes
+            // back before the failure is reported.
+            await releaseCrmEmailSend(firestore, claim.reservation);
+            throw error;
+        }
+        if (!result.sent) {
+            await releaseCrmEmailSend(firestore, claim.reservation);
+            return answer(res, sendRefusal(result));
+        }
+        const sentAtMs = Date.now();
+        let logged = true;
+        /*
+     * Who may list the row. Under a site, what a record created there is
+     * stamped with. At the organization level the RECORD's own tokens, so
+     * an email to a person another site captured shows on their timeline
+     * under that site's hub — a row stamped with the sending site alone
+     * would be invisible where the person is read.
+     */ const recordTokens = recipient.record['visibleTo'];
+        const visibleTo = routeScope.level === 'org' && Array.isArray(recordTokens) && recordTokens.length ? recordTokens.map(String) : crmScopeTokens(org, group);
+        try {
+            await writeCrmEmailActivity(activityRef, buildCrmEmailActivity(_extends({
+                subject,
+                body: text,
+                to: recipient.email,
+                atMs: sentAtMs,
+                byUid: sender.uid
+            }, sender.name ? {
+                byName: sender.name
+            } : {}, {
+                link: recipient.link,
+                hostId,
+                visibleTo
+            })));
+        } catch (error) {
+            // The message has left. A row that could not be written is a gap on
+            // the timeline, not a failed send, and it is said so in the answer.
+            console.error('[crm] email activity write failed', orgId, activityRef.id, error);
+            logged = false;
+        }
+        // The cap's count was taken with the reservation; the org's cost meter
+        // for COGS is stamped after delivery, unable to fail the send.
+        await recordEmailSends({
+            scope: {
+                kind: 'org',
+                orgId
+            },
+            count: 1,
+            sendClass: 'transactional',
+            firestore
+        });
+        // The org-level act, in the org's feed: the site variant's is the
+        // timeline row itself, under the site the record page is on.
+        if (routeScope.level === 'org') {
+            await logOrgActivity(orgId, {
+                uid: sender.uid,
+                email: sender.email
+            }, 'Sent email', recipient.link.contactId ? {
+                type: 'contact',
+                id: recipient.link.contactId,
+                name: recipient.email
+            } : {
+                type: 'lead',
+                id: recipient.link.leadId,
+                name: recipient.email
+            });
+        }
+        res.status(200).json({
+            ok: true,
+            activityId: activityRef.id,
+            to: recipient.email,
+            from: identity.from,
+            logged
+        });
+    } catch (error) {
+        console.error('[crm] email-send failed', routeScope, error);
+        res.status(500).json({
+            error: 'The email could not be sent.'
+        });
+    }
+};
+export default crmEmailSendHandler;
+
+//# sourceMappingURL=email-send.js.map