@masters-union/outbound-sdk 0.4.11 → 0.4.13

package/dist/index.d.mts

@@ -540,14 +540,37 @@ interface IncomingWebhookPayload {
 }
 /** Internal status a v2 event maps to (past-tense of `event`). */
 type WebhookEventStatus = 'sent' | 'delivered' | 'bounced' | 'complained' | 'opened' | 'clicked' | 'rejected' | 'rendering_failed' | 'dropped' | 'unsubscribed' | 'resubscribed' | 'ping';
+/**
+ * Why a recipient unsubscribed.
+ *
+ * The first four are chosen by the recipient on the unsubscribe page; the last two are
+ * assigned by the platform and can never be selected:
+ *  - `not_specified` — the form was submitted with the optional question unanswered.
+ *  - `one_click` — RFC 8058 List-Unsubscribe-Post, i.e. the mail client's own
+ *    unsubscribe button. No page is rendered on that path, so no reason can be asked.
+ *
+ * Codes are stable and will not be renamed. New codes may be added, so treat this as
+ * an open set when switching on it.
+ */
+type UnsubscribeReason = 'too_many_emails' | 'not_relevant' | 'never_signed_up' | 'other' | 'not_specified' | 'one_click';
+/** How an opt-out reached us: the link in the email, the mail client's header button, or the API. */
+type UnsubscribeSource = 'link' | 'one_click' | 'api';
 /** Curated, event-specific details. Only the keys relevant to the event are set. */
 interface WebhookEventDetails {
     /** bounce */
     bounceType?: string | null;
     bounceSubType?: string | null;
     smtpStatus?: string | null;
+    /**
+     * The receiving mail server's own diagnostic, with infrastructure-provider branding
+     * and provider documentation links removed. Display text, not a stable key.
+     */
     diagnosticCode?: string | null;
-    /** bounce / reject / rendering_failure / dropped (dropped carries the drop reason) */
+    /**
+     * bounce / reject / rendering_failure / dropped (dropped carries the drop reason).
+     * A stable Outbound sentence for known bounce subtypes, otherwise the remote
+     * diagnostic. Branch on `bounceType`/`bounceSubType`/`smtpStatus`, not on this.
+     */
     failedReason?: string | null;
     /** bounce / complaint — true when we auto-added the address to the suppression list */
     suppressed?: boolean;
@@ -558,6 +581,27 @@ interface WebhookEventDetails {
     ip?: string | null;
     /** click */
     link?: string | null;
+    /**
+     * unsubscribe — the reason the recipient gave, as a stable code. Branch on this,
+     * not on `unsubscribeReasonLabel`.
+     *
+     * `not_specified` means they submitted the form without answering the optional
+     * question. `one_click` means they used their mail client's own unsubscribe button
+     * (RFC 8058 List-Unsubscribe-Post), where no page is shown and so no reason can be
+     * asked — it is not a reason they chose.
+     */
+    unsubscribeReason?: UnsubscribeReason | null;
+    /** unsubscribe — display wording for {@link unsubscribeReason}. May be reworded; do not branch on it. */
+    unsubscribeReasonLabel?: string | null;
+    /** unsubscribe — how the opt-out reached us. */
+    unsubscribeSource?: UnsubscribeSource | null;
+    /**
+     * unsubscribe — optional free text, only ever collected alongside reason `other`.
+     *
+     * Recipient-authored and therefore untrusted: it is length-capped and stripped of
+     * control characters on the way in, but escape it before rendering it anywhere.
+     */
+    unsubscribeComment?: string | null;
 }
 /** A single event inside a v2 webhook delivery. */
 interface IncomingWebhookEventV2 {

package/dist/index.d.ts

@@ -540,14 +540,37 @@ interface IncomingWebhookPayload {
 }
 /** Internal status a v2 event maps to (past-tense of `event`). */
 type WebhookEventStatus = 'sent' | 'delivered' | 'bounced' | 'complained' | 'opened' | 'clicked' | 'rejected' | 'rendering_failed' | 'dropped' | 'unsubscribed' | 'resubscribed' | 'ping';
+/**
+ * Why a recipient unsubscribed.
+ *
+ * The first four are chosen by the recipient on the unsubscribe page; the last two are
+ * assigned by the platform and can never be selected:
+ *  - `not_specified` — the form was submitted with the optional question unanswered.
+ *  - `one_click` — RFC 8058 List-Unsubscribe-Post, i.e. the mail client's own
+ *    unsubscribe button. No page is rendered on that path, so no reason can be asked.
+ *
+ * Codes are stable and will not be renamed. New codes may be added, so treat this as
+ * an open set when switching on it.
+ */
+type UnsubscribeReason = 'too_many_emails' | 'not_relevant' | 'never_signed_up' | 'other' | 'not_specified' | 'one_click';
+/** How an opt-out reached us: the link in the email, the mail client's header button, or the API. */
+type UnsubscribeSource = 'link' | 'one_click' | 'api';
 /** Curated, event-specific details. Only the keys relevant to the event are set. */
 interface WebhookEventDetails {
     /** bounce */
     bounceType?: string | null;
     bounceSubType?: string | null;
     smtpStatus?: string | null;
+    /**
+     * The receiving mail server's own diagnostic, with infrastructure-provider branding
+     * and provider documentation links removed. Display text, not a stable key.
+     */
     diagnosticCode?: string | null;
-    /** bounce / reject / rendering_failure / dropped (dropped carries the drop reason) */
+    /**
+     * bounce / reject / rendering_failure / dropped (dropped carries the drop reason).
+     * A stable Outbound sentence for known bounce subtypes, otherwise the remote
+     * diagnostic. Branch on `bounceType`/`bounceSubType`/`smtpStatus`, not on this.
+     */
     failedReason?: string | null;
     /** bounce / complaint — true when we auto-added the address to the suppression list */
     suppressed?: boolean;
@@ -558,6 +581,27 @@ interface WebhookEventDetails {
     ip?: string | null;
     /** click */
     link?: string | null;
+    /**
+     * unsubscribe — the reason the recipient gave, as a stable code. Branch on this,
+     * not on `unsubscribeReasonLabel`.
+     *
+     * `not_specified` means they submitted the form without answering the optional
+     * question. `one_click` means they used their mail client's own unsubscribe button
+     * (RFC 8058 List-Unsubscribe-Post), where no page is shown and so no reason can be
+     * asked — it is not a reason they chose.
+     */
+    unsubscribeReason?: UnsubscribeReason | null;
+    /** unsubscribe — display wording for {@link unsubscribeReason}. May be reworded; do not branch on it. */
+    unsubscribeReasonLabel?: string | null;
+    /** unsubscribe — how the opt-out reached us. */
+    unsubscribeSource?: UnsubscribeSource | null;
+    /**
+     * unsubscribe — optional free text, only ever collected alongside reason `other`.
+     *
+     * Recipient-authored and therefore untrusted: it is length-capped and stripped of
+     * control characters on the way in, but escape it before rendering it anywhere.
+     */
+    unsubscribeComment?: string | null;
 }
 /** A single event inside a v2 webhook delivery. */
 interface IncomingWebhookEventV2 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masters-union/outbound-sdk",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Official Node.js SDK for the Outbound Email SaaS platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",