platform-types 1.10.679 → 1.10.680

package/dist/cjs/emailSuppression.js

@@ -0,0 +1,12 @@
+"use strict";
+// Suppressed email addresses, as a platform MANAGER sees them through
+// `/platform/email-suppression`. Two lists gate a send, and this surface reads both:
+//
+// - the APP list — one DynamoDB row per (store, address) under
+//   `EMAILSUPPRESSION#{storeId}` (or `#PLATFORM`), written by the SES event consumer
+//   or by a MANAGER, and enforced by the send path;
+// - the SES ACCOUNT list — maintained by SES itself. ⚠️ Dev and prod share one AWS
+//   account, so this list is shared across stages while app rows are per stage.
+//
+// ⚠️ Operator surface only. No tenant-tier route returns these shapes.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.js

@@ -56,6 +56,7 @@ __exportStar(require("./gating.js"), exports);
 __exportStar(require("./holdingCost.js"), exports);
 __exportStar(require("./demo.js"), exports);
 __exportStar(require("./emailIdentity.js"), exports);
+__exportStar(require("./emailSuppression.js"), exports);
 __exportStar(require("./impersonation.js"), exports);
 __exportStar(require("./imports.js"), exports);
 __exportStar(require("./inventory.js"), exports);

package/dist/emailSuppression.d.ts

@@ -0,0 +1,125 @@
+/** Why an app row suppresses. `'bounce'` blocks every send; `'complaint'` every send but transactional. */
+export type EmailSuppressionReason = 'bounce' | 'complaint';
+/** Who wrote the app row: the SES event consumer, or a MANAGER by hand. */
+export type EmailSuppressionSource = 'ses-event' | 'manager';
+/** SES's own reason on an account-list entry. */
+export type SesSuppressionReason = 'BOUNCE' | 'COMPLAINT';
+/** The app row's half of an entry. Fields written before the evidence was kept are absent. */
+export interface EmailSuppressionAppRow {
+    reason: EmailSuppressionReason;
+    source: EmailSuppressionSource;
+    firstSuppressedAt?: number;
+    lastEventAt?: number;
+    bounceType?: 'Permanent' | 'Transient' | 'Undetermined';
+    bounceSubType?: string;
+    /** Remote SMTP diagnostic text, at most 500 bytes. Never message content. */
+    diagnosticCode?: string;
+    sesMessageId?: string;
+    feedbackId?: string;
+    /** Present on a manual add only. */
+    actorUserId?: string;
+    /** Epoch seconds — the row's TTL. */
+    expiresAt: number;
+}
+/** The SES account list's half of an entry. */
+export interface EmailSuppressionSesEntry {
+    reason: SesSuppressionReason;
+    /** The exact spelling SES holds, when it differs from the lowercased `address`. */
+    address?: string;
+    /** ISO-8601, as SES reports it. */
+    lastUpdateTime: string;
+}
+/**
+ * One address in one scope. An address with app rows in two stores is two entries;
+ * the SES half (account-wide) rides on each of them. `storeId: null` is an SES-only
+ * entry with no app row anywhere.
+ */
+export interface EmailSuppressionEntry {
+    address: string;
+    storeId: string | 'PLATFORM' | null;
+    /** The store's display name when `storeId` names a store. */
+    storeName?: string;
+    app: EmailSuppressionAppRow | null;
+    ses: EmailSuppressionSesEntry | null;
+}
+/** `GET /platform/email-suppression` — `data`. Pass `nextCursor` back as `?cursor=`. */
+export interface EmailSuppressionListResponse {
+    items: EmailSuppressionEntry[];
+    nextCursor?: string;
+    /** A source was read up to its cap, so the merged view may be incomplete. */
+    truncated?: boolean;
+}
+/** One SES event for the address, from the store's `EMAILEVENT#` history. */
+export interface EmailSuppressionEvent {
+    storeId: string;
+    sesMessageId: string;
+    eventType: 'Bounce' | 'Complaint' | 'Delivery' | 'Reject' | 'Open' | 'Click';
+    bounceType?: 'Permanent' | 'Transient' | 'Undetermined';
+    createdAt: number;
+}
+/** `GET /platform/email-suppression/{address}` — `data`. */
+export interface EmailSuppressionDetail {
+    address: string;
+    /** One per app row, or a single SES-only entry; empty when the address is on neither list. */
+    entries: EmailSuppressionEntry[];
+    /** The newest events first, at most 20. */
+    events: EmailSuppressionEvent[];
+    /** The event read hit its bound before covering every store. */
+    eventsTruncated?: boolean;
+    /**
+     * `false` — the domain authoritatively accepts no mail (an RFC 7505 null MX, or it
+     * does not exist); `null` — unknown: the lookup did not answer, or the domain has no
+     * MX record and relies on an implicit MX.
+     */
+    mxPresent: boolean | null;
+    /** SES did not answer (throttle or timeout), so each entry's `ses` half is unknown, not absent. */
+    sesUnavailable?: boolean;
+}
+/** A non-blocking caution on a write. */
+export type EmailSuppressionWarning = 
+/** The MX lookup did not answer, or the domain relies on an implicit MX (A/AAAA only). */
+'MX_UNKNOWN'
+/** A permanent NoEmail/General bounce was recorded less than an hour ago. */
+ | 'RECENT_PERMANENT_BOUNCE'
+/** The store roster was read up to its cap, so a store's row may have been missed. */
+ | 'STORE_ROSTER_TRUNCATED';
+/**
+ * What happened to the SES account list. `'skipped'` — this stage does not write the
+ * SES list: dev and prod share one AWS account, so only prod may change it.
+ */
+export type EmailSuppressionSesWrite = 'removed' | 'absent' | 'skipped';
+/** `DELETE /platform/email-suppression/{address}` — body. Omit `storeId` to clear every store's row. */
+export interface EmailSuppressionDeleteRequest {
+    reason: string;
+    storeId?: string;
+}
+/** `DELETE /platform/email-suppression/{address}` — `data`. Idempotent: an absent entry is success. */
+export interface EmailSuppressionDeleteResponse {
+    app: 'removed' | 'absent';
+    ses: EmailSuppressionSesWrite;
+    warnings?: EmailSuppressionWarning[];
+}
+/**
+ * `POST /platform/email-suppression` — body. `'manual'` and `'bounce'` store an app `'bounce'`
+ * row and (prod only) an SES `BOUNCE` entry; `'complaint'` stores an app `'complaint'` row only.
+ * Omit `storeId` to suppress on the platform partition.
+ */
+export interface EmailSuppressionCreateRequest {
+    address: string;
+    reason: EmailSuppressionReason | 'manual';
+    note: string;
+    storeId?: string;
+}
+/** `POST /platform/email-suppression` — `data`. */
+export interface EmailSuppressionCreateResponse {
+    entry: EmailSuppressionEntry;
+    /**
+     * `'skipped'` on a stage that does not write the SES list (see {@link EmailSuppressionSesWrite}),
+     * and for a `'complaint'` add on every stage: the SES account list blocks EVERY send whatever
+     * its reason, so an SES COMPLAINT entry would also stop the transactional mail an app
+     * complaint row lets through.
+     */
+    ses: 'added' | 'skipped';
+    /** SES did not answer the read-back, so `entry.ses` is unknown, not absent. */
+    sesUnavailable?: boolean;
+}

package/dist/emailSuppression.js

@@ -0,0 +1,11 @@
+// Suppressed email addresses, as a platform MANAGER sees them through
+// `/platform/email-suppression`. Two lists gate a send, and this surface reads both:
+//
+// - the APP list — one DynamoDB row per (store, address) under
+//   `EMAILSUPPRESSION#{storeId}` (or `#PLATFORM`), written by the SES event consumer
+//   or by a MANAGER, and enforced by the send path;
+// - the SES ACCOUNT list — maintained by SES itself. ⚠️ Dev and prod share one AWS
+//   account, so this list is shared across stages while app rows are per stage.
+//
+// ⚠️ Operator surface only. No tenant-tier route returns these shapes.
+export {};

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export * from './gating.ts';
 export * from './holdingCost.ts';
 export * from './demo.ts';
 export * from './emailIdentity.ts';
+export * from './emailSuppression.ts';
 export * from './impersonation.ts';
 export * from './imports.ts';
 export * from './inventory.ts';

package/dist/index.js

@@ -40,6 +40,7 @@ export * from "./gating.js";
 export * from "./holdingCost.js";
 export * from "./demo.js";
 export * from "./emailIdentity.js";
+export * from "./emailSuppression.js";
 export * from "./impersonation.js";
 export * from "./imports.js";
 export * from "./inventory.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.679",
+	"version": "1.10.680",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",