@aglyn/plugins-marketing 1.0.0-beta.143

package/src/lib/server/campaign-send.d.ts

@@ -0,0 +1,487 @@
+/**
+ * @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 { type PluginApiHandler } from '@aglyn/aglyn/server';
+import { type SendingIdentitySource } from '@aglyn/shared-util-email';
+/**
+ * Stable doc id for a suppression entry (emails are PII — hash them).
+ *
+ * A WRITER's derivation now — `email-events.ts` files bounces and complaints
+ * under it. The send path reads through `emailSuppressionKey`, which hashes
+ * the same trimmed, lowercased form and additionally refuses to guess an id
+ * for a value that is not an address.
+ */
+export declare function suppressionId(email: string): string;
+/** HMAC for unsubscribe links; env-gated on the shared secret. */
+export declare function unsubscribeSignature(hostId: string, email: string, secret: string, campaignId?: string, topicId?: string): string;
+/** Send failures carry the HTTP status the API route should answer. */
+export declare class CampaignSendError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * The platform send rate had no room for this campaign THIS HOUR (AGL-2409).
+ *
+ * A subclass rather than a status code the caller has to recognise, because
+ * the difference it carries is not "which HTTP number" — it is **retry, do not
+ * fail**. A scheduled campaign that trips the hourly ceiling must go back to
+ * `scheduled` and be picked up by the next 15-minute run; marking it `failed`,
+ * which is what every other `CampaignSendError` correctly does, would turn a
+ * ramp into a lost campaign that a merchant has to notice and re-create.
+ *
+ * Thrown ONLY before anything has been sent, so a caller that retries cannot
+ * double-send.
+ */
+export declare class CampaignSendDeferredError extends CampaignSendError {
+    /** When the hourly window rolls. */
+    readonly retryAtMs: number;
+    constructor(message: string, 
+    /** When the hourly window rolls. */
+    retryAtMs: number);
+}
+export interface CampaignSendOptions {
+    hostId: string;
+    subject: string;
+    /**
+     * The MESSAGE of a plain-text email — what recipients read, and what the
+     * HTML part is synthesized from.
+     *
+     * Not read on a designed send, where the nodes are the message. The route
+     * refuses a request carrying both rather than accepting one and dropping it,
+     * which is what it used to do.
+     */
+    body: string;
+    audience: string;
+    segmentId?: string;
+    listId?: string;
+    /**
+     * The stream this campaign belongs to, chosen in the composer.
+     *
+     * Resolved to {@link DEFAULT_CAMPAIGN_TOPIC_ID} when absent, so every send
+     * belongs to some topic: a campaign with none would mint an unsubscribe link
+     * the preference page can render but not place, offering the recipient a
+     * catalog without saying which entry the message in front of them was.
+     */
+    topicId?: string;
+    /**
+     * Resolve the audience and return the count WITHOUT sending anything
+     * (AGL-2178). Returns before the first write, so it mints no campaign
+     * id and touches no counter.
+     */
+    dryRun?: boolean;
+    emails?: string[];
+    campaignId?: string;
+    experimentId?: string;
+    /**
+     * Designed email template (AGL-349): screen id of a besigner email
+     * document, which is what makes this a DESIGNED send.
+     *
+     * The nodes produce both parts an inbox receives — the HTML and a plain-text
+     * rendering of the same design — so `body` has no job here and is not read.
+     * `plainText` below is the one thing an author may substitute.
+     */
+    templateScreenId?: string;
+    /**
+     * The author's own PLAIN-TEXT PART for a designed email.
+     *
+     * Empty means the design generates it, which is the default and what every
+     * designed campaign did before this existed. Read only on the designed
+     * path: a plain-text campaign's text part IS its body, and a second string
+     * claiming to be the text part beside it would be the two-sources problem
+     * again under a new name.
+     */
+    plainText?: string;
+    /**
+     * The sender's DISPLAY NAME for this campaign, overriding the org's
+     * branding default.
+     *
+     * A display name and nothing more: `applyFromName` keeps the verified
+     * address it is applied to, so this cannot move the mail onto a domain the
+     * org has not proved. The route strips control characters before it gets
+     * here, because the value is merchant-typed and lands in a header.
+     */
+    fromName?: string;
+    /** Where replies go, when it is not the sending address. */
+    replyTo?: string;
+    /**
+     * WHICH OF THE SITE'S SENDERS THIS EMAIL LEAVES AS —
+     * `hosts/{hostId}/senders/{senderId}`.
+     *
+     * The mailbox, and only the mailbox. A sender also carries a display name
+     * and a reply address, and those stay per-send fields resolved from
+     * {@link fromName} and {@link replyTo}: the composer seeds them from the
+     * chosen sender so a merchant sees what will go out, and the send records
+     * what was submitted, which is what keeps the stored report and the message
+     * one answer rather than two.
+     *
+     * ## An id, which is not the input path that was closed
+     *
+     * `req.body.sendingIdentity` is read by nothing, and a per-send local part
+     * would reopen it: a mailbox is where a bounce returns and where a client
+     * ignoring `Reply-To:` answers, so one that exists in a single campaign's
+     * headers is an address nobody serves. A sender id names a mailbox that was
+     * configured once, validated once and stored on this site under an
+     * `org.settings` gate. The set of addresses this field can reach is the set
+     * an org admin already approved.
+     *
+     * Absent means the site's DEFAULT sender, which is the projection the host
+     * document has always carried. Naming a sender this site does not hold is
+     * REFUSED — see the resolution below — rather than falling back to it.
+     */
+    senderId?: string;
+    /**
+     * The CAMPAIGN this send belongs to — `hosts/{hostId}/emailCampaigns/{id}`.
+     *
+     * Not the send's own id, which is what `campaignId` means here and what
+     * every delivered unsubscribe link carries as `cid`. Absent on a send
+     * composed outside a campaign, and on every send that predates containers;
+     * the campaigns list adopts those as a campaign of one at read time rather
+     * than rewriting them.
+     */
+    emailCampaignId?: string;
+    /**
+     * The preview line inboxes show after the subject. Overrides a designed
+     * template's own, and gives a plain-text campaign one at all.
+     */
+    preheader?: string;
+    /**
+     * What the merchant called this email, for the record rather than for the
+     * recipient.
+     *
+     * Never leaves the console — it is not the subject and reaches no header,
+     * so it is stored as typed apart from a length cap. Absent on every send
+     * composed from a campaign, where the campaign is what carries the name.
+     */
+    displayName?: string;
+    /** Test sends (AGL-349) skip the campaign record and stats. */
+    recordCampaign?: boolean;
+    /**
+     * SEND THIS EMAIL AGAIN, TO PEOPLE IT HAS NOT REACHED.
+     *
+     * Set with a `campaignId` naming a send that has already gone out. The send
+     * is not copied and no second document is made: this send addresses the
+     * same audience under the same id, minus everyone the earlier sends
+     * reached, and ADDS to the counters already on the record.
+     *
+     * ## Why the same document, rather than a new send
+     *
+     * Two reasons, and both are properties a copy would break.
+     *
+     * The unsubscribe link is the first. Every message this email has already
+     * delivered carries `cid={campaignId}` inside its own HMAC, and those
+     * messages sit in inboxes forever. A follow-up under a new id would be a
+     * second `cid` for one email — two opt-out scopes for one mailing, and an
+     * unsubscribe rate split across two records neither of which is the answer.
+     *
+     * The report is the second. Opens and clicks are attributed by the
+     * `campaignId` tag on the delivered message, so a copy would collect the
+     * follow-up's engagement on a document whose `sent` counts only the
+     * follow-up. Keeping one document keeps every rate over a denominator that
+     * covers the same mail the numerator does — see the additive write at the
+     * bottom of this function for the arithmetic that holds it.
+     *
+     * ## What it does NOT relax
+     *
+     * Nothing. The follow-up runs the whole of this function: the consent
+     * split, both suppression lists, the topic filter, the monthly pre-check
+     * and reservation, the platform and per-workspace hourly ceilings, and the
+     * per-message governor. Its only additions are the subtraction below and
+     * the shape of the write at the end.
+     */
+    followUp?: boolean;
+    /**
+     * THE NEXT BATCH OF AN EMAIL THAT IS STILL GOING OUT.
+     *
+     * Set by the scheduled-campaign processor, never by a request. An audience
+     * larger than {@link EMAIL_MAX_RECIPIENTS_PER_SEND} is delivered across
+     * several invocations; each one addresses the people the earlier ones did
+     * not, and the campaign is written back as `scheduled` until nothing is
+     * left. See the batch plan at the bottom of this function.
+     *
+     * ## Why it is not {@link followUp}
+     *
+     * They share the subtraction and the additive write, and they differ on the
+     * two things that matter. A follow-up is a MERCHANT's act on an email that
+     * has finished — it subtracts who was reached, and somebody suppressed at
+     * the time who has since been released is entitled to get it. A batch is
+     * one email still in flight — it subtracts everyone the email has SETTLED,
+     * reached or refused, because a refused address sitting at the head of a
+     * stable order would consume a slot in every remaining batch and, in
+     * enough numbers, stop the campaign dead having mailed nobody.
+     *
+     * They also record differently. A follow-up measures a NEW population, so
+     * the audience size and the consent split add. A batch measures a slice of
+     * the population the first batch already measured, so those figures are
+     * left exactly as the first batch wrote them.
+     */
+    continuation?: boolean;
+    /**
+     * ONE address the caller has been proved to be entitled to proof to, for
+     * the composer's test send. Exempts exactly this address from the
+     * marketing-consent rule.
+     *
+     * The route decides entitlement and this file decides what the exemption
+     * can do. See {@link eligibleProofAddress} for the first half and the
+     * carve-out at the consent join for the second — including the two
+     * properties that keep the exemption one address wide however the caller
+     * arrived at it.
+     */
+    proofFor?: string;
+    /**
+     * Test send only: render every message as if it were addressed to this
+     * person, while DELIVERING to the recipient resolved in the ordinary way.
+     *
+     * What a merge tag resolves to is the whole question a proof answers. A
+     * test rendered against the tester shows `{{firstName|there}}` falling back
+     * for an audience whose contacts all have names, which reports the merge
+     * tags as broken when they work — and, more expensively, hides the reverse.
+     *
+     * It changes the RENDER and nothing else. The unsubscribe link, the
+     * `List-Unsubscribe` header and the suppression key are all minted from the
+     * delivery address, deliberately: a proof carrying the persona's opt-out
+     * link would let the person testing the email unsubscribe a real contact by
+     * clicking a link in their own inbox.
+     */
+    proofPersona?: {
+        email: string;
+        name?: string;
+    };
+    /** Recorded as `sentBy`; the scheduler passes the scheduling user. */
+    senderUid: string;
+}
+/**
+ * Campaign delivery core (AGL-161, extracted for AGL-272): resolves the
+ * audience server-side, drops suppressed addresses, enforces the plan's
+ * monthly send cap, personalizes merge tags per recipient, and delivers
+ * through Resend with a signed unsubscribe link. Shared by the
+ * authenticated send route and the scheduled-campaign processor. The
+ * caller owns authorization.
+ */
+export interface CampaignSendResult {
+    campaignId: string;
+    /** Addresses this send ADDRESSED — the audience after the per-send cap. */
+    recipients: number;
+    sent: number;
+    /**
+     * The whole audience, deduplicated and validated, BEFORE the per-send cap.
+     *
+     * Reported separately from `recipients` because the two differ whenever an
+     * audience is larger than one send may carry, and a merchant who is only
+     * shown the smaller number has no way to learn that the rest were never
+     * mailed. `recipients` of 500 against an `audienceSize` of 3,000 is the
+     * whole point of the field.
+     *
+     * Named for the SIZE because `audience` on the options and on the stored
+     * campaign is the audience KIND — `'leads'`, `'list'` — and one word
+     * meaning both a name and a count on the same send path is how the two get
+     * read into each other.
+     */
+    audienceSize: number;
+    /**
+     * `audienceSize` is a FLOOR, not a total: the resolution stopped at its
+     * read ceiling with documents still unread. Absent means it is exact.
+     */
+    audienceTruncated?: boolean;
+    /**
+     * Dry run only (AGL-2178): recipients that will actually be mailed —
+     * after the consent join, the per-send cap and both suppression lists.
+     */
+    sendable?: number;
+    /** Dry run only: of `audienceSize`, how many carry a recorded consent basis. */
+    consented?: number;
+    /**
+     * Dry run only: of `consented`, how many hold a basis an OPERATOR asserted
+     * on their behalf rather than one they gave — a backfill over seed data,
+     * say. A subset of `consented` and not a fourth population.
+     */
+    consentedByOperator?: number;
+    /**
+     * Dry run only: of `audienceSize`, how many are reachable only because
+     * consent enforcement is not retroactive. This is the population a strict
+     * policy would remove.
+     */
+    grandfathered?: number;
+    /** Dry run only: how many of `audienceSize` the consent rule refused. */
+    consentWithheld?: number;
+    /**
+     * Dry run only: how many of `recipients` are suppressed or off-topic.
+     *
+     * Not netted with {@link cadenceHeld}: leaving this site and asking it for
+     * less mail are different statements, and only one of them is a list a
+     * merchant has to rebuild.
+     */
+    suppressed?: number;
+    /**
+     * Dry run only: how many of `recipients` asked this site for mail less
+     * often than this send would arrive.
+     *
+     * They stay on every audience they were on and are mailed by the next
+     * campaign that falls outside their interval — the filter refuses a SEND,
+     * never a person.
+     */
+    cadenceHeld?: number;
+    /** Dry run only: which sending identity this campaign would leave on. */
+    identity?: string;
+    /**
+     * Dry run only: which KIND of identity this campaign would leave on.
+     *
+     * The union from the resolver rather than a local copy of it, so a new arm
+     * cannot be added there and silently narrowed here. `'shared'` never reaches
+     * a real campaign — the resolution above declares `purpose: 'marketing'`, and
+     * a pooled identity refuses before this is assembled — but the type says what
+     * the resolver can return, not what this path expects to see.
+     */
+    identitySource?: SendingIdentitySource | null;
+    dryRun?: boolean;
+    /** Recipients the hourly governor refused mid-batch (AGL-2409). */
+    deferred?: number;
+    /**
+     * Follow-up only: people in the audience this email had already reached, and
+     * which this send therefore did not address.
+     *
+     * Reported rather than netted away, because it is the number that explains
+     * the other ones. A follow-up over a 3,000-person list that addresses 40
+     * people has not failed — 2,960 of them already have the email — and
+     * without this figure the merchant cannot tell that from a broken audience.
+     */
+    alreadyReached?: number;
+    /** Whether this send added to an existing email rather than starting one. */
+    followUp?: boolean;
+    /**
+     * People this email has resolved and not yet addressed.
+     *
+     * Non-zero on a send that is still going out, and the figure that makes
+     * "reached 500 of 3,000" a sentence rather than a truncation. Zero when the
+     * email is finished.
+     */
+    remaining?: number;
+    /** True when another batch of this email will run on its own. */
+    resuming?: boolean;
+    /** When the next batch may go, ms. Present only while {@link resuming}. */
+    nextAtMs?: number;
+    /** Batches this email has run, including this one. */
+    batch?: number;
+}
+export declare function performCampaignSend(options: CampaignSendOptions): Promise<CampaignSendResult>;
+/**
+ * The stored configuration of a send, as the options that would mail it.
+ *
+ * Every field comes off the RECORD and none of it off the request — the
+ * caller names a site and an email id and nothing else. That is not tidiness:
+ * `campaignId` addresses an existing document, so a caller who could also
+ * supply the body and the audience could put arbitrary copy on somebody
+ * else's send id, keep its `cid` and its report, and mail it.
+ *
+ * Both callers rest on that. A follow-up mails the email that is already
+ * there; `sendNow` mails a draft or a scheduled email ahead of its time, and
+ * the copy it delivers has to be the copy that was composed and previewed
+ * rather than whatever a request body happens to carry.
+ *
+ * Refuses a send carrying neither a template nor a body, which has no message
+ * whichever caller asked.
+ */
+/** One address a test send is allowed to be delivered to. */
+export interface ProofRecipient {
+    email: string;
+    /** A person's name where the membership record carries one. */
+    label: string;
+    /** True for the caller's own account address. */
+    self: boolean;
+}
+/**
+ * THE ADDRESSES A TEST SEND MAY BE DELIVERED TO.
+ *
+ * The caller's own account address, plus every account holder on the org that
+ * owns this site. Exported because the composer has to OFFER this set — a
+ * free-text box beside a rule enforced on the server is a box whose every
+ * wrong answer is a refusal the person could not have predicted.
+ *
+ * ## Why membership, and not "any address the merchant types"
+ *
+ * A test send is exempt from the marketing-consent rule (see the proof
+ * carve-out in `performCampaignSend`). An exemption that could be pointed at
+ * any address would not be a test-send feature, it would be a way to mail
+ * anybody without consent and call it a test. Membership is the narrowest
+ * boundary that still answers what the button is for: proofing a draft to the
+ * people who work on it.
+ *
+ * ## What is NOT here
+ *
+ * `siteMembers`, `leads` and contacts. They are the tenant's audience, and
+ * the audience is precisely the population the consent rule protects. A
+ * contact can be chosen as the PERSONA a proof renders as — see
+ * {@link resolveProofPersona} — which reaches nobody.
+ *
+ * ## What this does not relax
+ *
+ * Everything else. The send still runs both suppression lists, so an address
+ * that bounced or complained is refused however senior its owner; and a
+ * stored `declined` on the address still refuses, because a refusal is the
+ * one thing no policy may mail.
+ */
+export declare function proofRecipientsForHost(options: {
+    hostId: string;
+    callerEmail: string;
+}): Promise<ProofRecipient[]>;
+/** One person a proof can be rendered as. Reaches nobody. */
+export interface ProofPersona {
+    email: string;
+    name: string;
+    /** Which audience the record came from, so the drawer can say. */
+    source: 'lead' | 'member' | 'contact';
+}
+/**
+ * A SAMPLE of the people this site's mail is addressed to, for the picker.
+ *
+ * A sample and not a search: the question the drawer asks is "show me this
+ * email as somebody real", and twenty names from each source answers it for
+ * the cost of three small reads. A contact picker with a query behind it is a
+ * different feature, and it would put a text input in front of the org's
+ * whole contact list on a surface whose job is to prove one email.
+ *
+ * Ordered by document id in every source, because a `limit` with no `orderBy`
+ * is a random sample in doc-id order that a client `sort` then makes LOOK
+ * newest-first. Naming the order keeps the picker stable between openings —
+ * and on the org path it is also the order the automatic index for the scope
+ * filter can actually serve.
+ */
+export declare function proofPersonasForHost(hostId: string): Promise<ProofPersona[]>;
+/**
+ * Campaign API (AGL-161/272): `action` picks the operation.
+ *
+ * Every one of them requires a site admin or editor.
+ *
+ * ## The ones that mail something
+ *
+ * `send` (the default) delivers copy carried in the request. `sendNow` mails
+ * a draft or a scheduled email ahead of its time, and `followUp` mails an
+ * already-sent one to the people it has not reached; both of those take every
+ * field off the RECORD rather than the request. `test` delivers to the caller
+ * alone and records nothing.
+ *
+ * ## The ones that only write
+ *
+ * `draft` stores an email that has not been sent, `schedule` stores one with
+ * a `sendAtMs` for the processor to deliver, `update` corrects the merchant's
+ * own name for an email at any point in its life, and `cancel` withdraws a
+ * scheduled one. None of them reserves allowance or moves a meter.
+ *
+ * ## The ones that answer a question
+ *
+ * `preview` resolves the audience and reports the counts, `renderPreview`
+ * renders the composed message. Neither writes.
+ */
+export declare const campaignSendHandler: PluginApiHandler;