@framers/agentos-ext-channel-email 0.6.2 → 0.6.4

package/dist/unsubscribe.d.ts

@@ -0,0 +1,208 @@
+import type { RecipientCapability } from './preferences/RecipientCapability.js';
+import type { SuppressionStore } from './preferences/SuppressionStore.js';
+/**
+ * The list every send reads, required mail and replies included: an address on it gets no mail at all. An operator
+ * writes it, such as for a person who asked never to be written to again.
+ */
+export declare const DO_NOT_CONTACT_SCOPE = "do-not-contact";
+/** The list of the addresses that turned off every optional mail: a required mail's link, and the page's second button, write it. */
+export declare const OPTIONAL_MAIL_SCOPE = "optional";
+/** What a part may hold where its link goes: the service writes the link there and adds no footer to that part. */
+export declare const UNSUBSCRIBE_URL_MARKER = "{{unsubscribe_url}}";
+/** How the record names an address: 64 lower-case hexadecimal characters, which the route reads a token's recipient by. */
+export declare const ADDRESS_HASH: RegExp;
+/**
+ * The list of one category of optional mail, `optional:` and the category: its link writes it, and every optional send
+ * of the category reads it.
+ *
+ * @param category A lower-case letter followed by at most 63 lower-case letters, digits, hyphens or underscores.
+ * @throws TypeError when the category does not fit.
+ */
+export declare function categoryScope(category: string): string;
+/**
+ * The category a list names, or `null` when it is no category's list. `OPTIONAL_MAIL_SCOPE` is no category's list.
+ *
+ * @param scope A suppression list's name.
+ */
+export declare function categoryOfScope(scope: string): string | null;
+/** The configuration's `unsubscribe`: what every mail the service sends then carries, and what it reads first. */
+export interface UnsubscribeOptions {
+    /**
+     * The page each link opens and the address a mailbox provider's one-click POST goes to: an https address with no
+     * query, fragment or credentials, 900 characters at most. A link is it with `?t=` and the token.
+     */
+    readonly pageUrl: string;
+    /**
+     * An address at the sender that takes unsubscribe requests by mail, listed after the link in `List-Unsubscribe` as
+     * `mailto:` with the subject `unsubscribe`. Leave it out when nothing reads that mailbox.
+     */
+    readonly mailto?: string;
+    /** Where the tokens are drawn, such as `SqlRecipientCapability`; the route finds them in the same store. */
+    readonly tokens: RecipientCapability;
+    /** The suppression record read before each send, such as `SqlSuppressionStore`; the route writes it. */
+    readonly suppressions: SuppressionStore;
+    /**
+     * The key the tokens are drawn under, 32 random bytes or more kept secret, or a function that answers it at each send
+     * so a rotated key applies at once.
+     */
+    readonly key: Uint8Array | (() => Uint8Array);
+    /**
+     * The keys tokens were drawn under before `key`, or a function that answers them at each send: list a rotated key
+     * while a send under an idempotency key may still be retried, 24 hours through Resend. A retry then finds the token
+     * its first attempt drew and carries the same link, since Resend answers a changed payload under the same
+     * Idempotency-Key with 409 `invalid_idempotent_request`. Each is 32 bytes or more.
+     */
+    readonly retiredKeys?: readonly Uint8Array[] | (() => readonly Uint8Array[]);
+    /**
+     * How the record names an address, given the address trimmed and lower-cased: 64 lower-case hexadecimal characters,
+     * the same way wherever the host reads or writes the record. The SHA-256 of the address in hex when not given. A send
+     * whose address it names any other way is refused with a `TypeError` before any list is read.
+     */
+    readonly addressHash?: (address: string) => string;
+    /**
+     * The sender's postal address on one line, printed at the foot of every mail. Commercial mail is refused without it,
+     * since CAN-SPAM asks a commercial mail for the sender's valid physical postal address (15 U.S.C. 7704(a)(5)).
+     */
+    readonly postalAddress?: string;
+    /** The category of the mail the `emailSend` tool and the channel adapter send: `conversation` when not given. */
+    readonly agentCategory?: string;
+    /** The words of the footer's link: `Unsubscribe` when not given. */
+    readonly linkText?: string;
+}
+/** What one send says of its mail. */
+export interface UnsubscribeKind {
+    /** The category of optional mail, which its link stops; required mail may name one too, which changes nothing. */
+    readonly category?: unknown;
+    /** Mail a person cannot turn off: sign-in codes, receipts, security and legal notices. */
+    readonly required?: unknown;
+    /** Advertising mail: optional, and carrying the postal address. */
+    readonly commercial?: unknown;
+}
+/** The lists one send reads, in order, the list its link writes, and whether it is commercial. */
+export interface UnsubscribePlan {
+    readonly reads: readonly string[];
+    readonly tokenScope: string;
+    readonly commercial: boolean;
+}
+/** What a send carries: its link, and the two fields that name it. */
+export interface UnsubscribeLink {
+    readonly url: string;
+    readonly headers: Readonly<Record<'List-Unsubscribe' | 'List-Unsubscribe-Post', string>>;
+}
+/**
+ * A send the suppression record stopped: nothing was sent and no token was drawn. `scope` names the list that held the
+ * address; the message names it too, and never the address.
+ */
+export declare class EmailSuppressedError extends Error {
+    /** Always `suppressed`. */
+    readonly code: "suppressed";
+    /** The list that held the address: `DO_NOT_CONTACT_SCOPE`, `DEFAULT_SUPPRESSION_SCOPE`, `OPTIONAL_MAIL_SCOPE` or a category's list. */
+    readonly scope: string;
+    constructor(scope: string);
+}
+/** A line of a footer or a page, checked: text on one line, not blank, `most` characters at most. */
+export declare function requireLine(field: string, value: unknown, most: number): string;
+/** Text written into HTML, its five special characters as references. */
+export declare function escapeHtml(text: string): string;
+/**
+ * The one address a recipient names, trimmed and lower-cased: `reader@example.com` or `Reader <reader@example.com>`.
+ * A list of addresses, a group, or a display name holding an address is refused with a `TypeError` that holds none of
+ * it, since a link names one recipient.
+ *
+ * @param to The recipient as the send gives it.
+ */
+export declare function oneRecipient(to: unknown): string;
+/**
+ * Refuses a cc or a bcc while unsubscribe links are on: a link names one recipient, so each person gets a message of
+ * their own.
+ */
+export declare function refuseCopies(cc: unknown, bcc: unknown): void;
+/** Refuses the two fields the service writes itself while unsubscribe links are on, in any case. */
+export declare function refuseOwnListFields(headers: Record<string, string> | undefined): void;
+/**
+ * The checked `unsubscribe` configuration of one service: the plan of each send, the gate and the token, and the
+ * footer of each part.
+ */
+export declare class Unsubscribe {
+    private readonly pageUrl;
+    private readonly mailto;
+    private readonly tokens;
+    private readonly suppressions;
+    private readonly key;
+    private readonly retiredKeys;
+    private readonly hash;
+    private readonly linkText;
+    /** The sender's postal address, or `undefined`. */
+    readonly postalAddress: string | undefined;
+    /** The category of the mail the `emailSend` tool and the channel adapter send. */
+    readonly agentCategory: string;
+    /**
+     * Checks every option, and throws a `TypeError` that names the first one at fault and holds none of its value.
+     *
+     * @param options The configuration's `unsubscribe`.
+     */
+    constructor(options: UnsubscribeOptions);
+    /**
+     * The plan of one send, from its kind: required mail reads the do-not-contact list alone and its link turns off every
+     * optional mail; optional mail names its category, reads the do-not-contact list, the provider's record
+     * (`DEFAULT_SUPPRESSION_SCOPE`), the list of all optional mail and its category's list, and its link stops the
+     * category. Throws before anything is read for a kind that does not fit: optional mail that names no category, a
+     * category that is not a lower-case word, required mail marked commercial, or commercial mail with no postal address
+     * configured.
+     *
+     * @param kind What the send says of its mail.
+     */
+    plan(kind: UnsubscribeKind): UnsubscribePlan;
+    /** The plan of a reply, and of required mail: the do-not-contact list alone, and a link that turns off every optional mail. */
+    replyPlan(): UnsubscribePlan;
+    /**
+     * Names the address by `addressHash`, and throws a `TypeError` that holds neither the address nor the name when the
+     * name is not 64 lower-case hexadecimal characters, since the route would find no link drawn for it. Then reads each of
+     * the plan's lists for the address and throws `EmailSuppressedError` for the first that holds it, then
+     * draws the token and answers the link with its two fields. A nonce of the send's own, such as its idempotency key,
+     * gives a retry the same token, the one a retired key drew when its first attempt came before a rotation; without one
+     * each send draws a new one.
+     *
+     * @param address The recipient, trimmed and lower-cased, as `oneRecipient` answers it.
+     * @param plan The send's plan.
+     * @param nonce The send's nonce, or `undefined` for a new one.
+     */
+    prepare(address: string, plan: UnsubscribePlan, nonce: string | undefined): Promise<UnsubscribeLink>;
+    /**
+     * Reads the do-not-contact list for every address a message names as its sender, trimmed and lower-cased, and throws
+     * `EmailSuppressedError` when it holds any of them, before anything is drawn or sent: a person on the list gets no
+     * reply, whichever of their addresses the reply would go to. An empty list reads nothing.
+     *
+     * @param addresses The addresses of the message's From, Sender and Reply-To.
+     */
+    refuseDoNotContact(addresses: readonly string[]): Promise<void>;
+    /** The record's name for an address by `addressHash`, refused when the route could not read it. */
+    private nameOf;
+    /** The token for the nonce under the current key. */
+    private draw;
+    /** The token a retired key drew for this nonce, recipient and scope, or `null` when none did or it no longer works. */
+    private drawnBefore;
+    /**
+     * The text part with its link: where it holds `UNSUBSCRIBE_URL_MARKER`, the link written in place of each, and the
+     * postal address after a blank line when commercial mail does not hold it already; otherwise a blank line, the link's
+     * words and the link, and the postal address on the next line when one is configured.
+     *
+     * @param body The text part as given.
+     * @param url The send's link.
+     * @param commercial Whether the mail is commercial.
+     */
+    text(body: string, url: string, commercial: boolean): string;
+    /**
+     * The HTML part with its link: where it holds `UNSUBSCRIBE_URL_MARKER` in its text or a tag's attribute, the link
+     * written in place of each, and a paragraph with the postal address before `</body>` when commercial mail does not hold
+     * it already; otherwise a paragraph in 13-pixel text before `</body>`, or at the end when the part has none, with the
+     * link and the postal address under it when one is configured. A marker only in a comment, a script, a style, a title,
+     * a textarea or a template is written as the link too, and the part still gets the paragraph, since no reader sees it.
+     *
+     * @param html The HTML part as given.
+     * @param url The send's link.
+     * @param commercial Whether the mail is commercial.
+     */
+    html(html: string, url: string, commercial: boolean): string;
+}
+//# sourceMappingURL=unsubscribe.d.ts.map

package/dist/unsubscribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsubscribe.d.ts","sourceRoot":"","sources":["../src/unsubscribe.ts"],"names":[],"mappings":"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"}