@sempdev/semp 0.4.3

package/dist/delivery/ack.js

@@ -0,0 +1,141 @@
+/**
+ * Per-attempt delivery acknowledgment objects per DELIVERY.md §1.
+ *
+ * A recipient server returns exactly one of three acknowledgments
+ * for every envelope delivery attempt:
+ *
+ *   - `delivered`  — accepted; carries a signed
+ *     {@link "./receipt".DeliveryReceipt} per §1.1.1, MAY include a
+ *     {@link RecipientStatus} per §1.6 if the sender matches the
+ *     recipient's visibility rules.
+ *   - `rejected`   — explicitly refused with a reason code per §1.2.
+ *   - `silent`     — no response within the sender's timeout window
+ *     per §1.3. The wire form for silent is "no response sent at
+ *     all"; this module exposes a constant value the sending server
+ *     uses internally to record the outcome on its own queue state.
+ *
+ * The {@link DeliveryAck} JSON shape is what the recipient server
+ * places in its response body (§1.1.1.5 example).
+ *
+ * @module
+ */
+/** Maximum length of {@link RecipientStatus.message} per §1.6.2. */
+export const MaxStatusMessageBytes = 256;
+/**
+ * Build a `delivered` ack from a signed receipt and optional
+ * recipient status. Per §1.6.4 the caller is responsible for
+ * deciding whether `recipientStatus` should be attached at all
+ * (call {@link matchVisibility} first).
+ */
+export function buildDeliveredAck(receipt, recipientStatus) {
+    const ack = {
+        acknowledgment: "delivered",
+        receipt,
+    };
+    if (recipientStatus !== undefined) {
+        ack.recipient_status = recipientStatus;
+    }
+    return ack;
+}
+/** Build a `rejected` ack with a reason code and optional reason text. */
+export function buildRejectedAck(reasonCode, reason) {
+    const ack = {
+        acknowledgment: "rejected",
+        reason_code: reasonCode,
+    };
+    if (reason !== undefined && reason !== "") {
+        ack.reason = reason;
+    }
+    return ack;
+}
+/**
+ * Resolve visibility per §1.6.4. Returns true when the
+ * recipient_status should be attached to the acknowledgment.
+ *
+ *  - `nobody` (default): never disclose, regardless of the allow list.
+ *  - `everyone`: always disclose, regardless of the allow list.
+ *  - `domains` / `servers` / `users`: walk the allow list looking for
+ *    a match. The mode constrains which entry kinds are honored — in
+ *    `domains` mode only entries with `type: "domain"`, etc.
+ *    Mismatched entries in the allow list are ignored.
+ *
+ * All comparisons are case-insensitive. Multiple rules combine as a
+ * union: any matching entry returns true.
+ *
+ * A nil/undefined visibility (no configuration at all) is equivalent
+ * to mode=nobody.
+ */
+export function matchVisibility(visibility, sender) {
+    if (visibility === undefined) {
+        return false;
+    }
+    switch (visibility.mode) {
+        case "nobody":
+            return false;
+        case "everyone":
+            return true;
+        case "domains":
+        case "servers":
+        case "users":
+            break;
+        default:
+            // Unknown mode — fail closed.
+            return false;
+    }
+    const senderAddress = (sender.address ?? "").toLowerCase();
+    const senderDomain = (sender.domain ?? "").toLowerCase();
+    const senderServer = (sender.server ?? "").toLowerCase();
+    const allow = visibility.allow ?? [];
+    for (const entry of allow) {
+        switch (entry.type) {
+            case "domain":
+                if (visibility.mode !== "domains") {
+                    continue;
+                }
+                if (senderDomain !== "" &&
+                    (entry.domain ?? "").toLowerCase() === senderDomain) {
+                    return true;
+                }
+                break;
+            case "server":
+                if (visibility.mode !== "servers") {
+                    continue;
+                }
+                if (senderServer !== "" &&
+                    (entry.server ?? "").toLowerCase() === senderServer) {
+                    return true;
+                }
+                break;
+            case "user":
+                if (visibility.mode !== "users") {
+                    continue;
+                }
+                if (senderAddress !== "" &&
+                    (entry.address ?? "").toLowerCase() === senderAddress) {
+                    return true;
+                }
+                break;
+            default:
+                // Unknown entry type — skip.
+                break;
+        }
+    }
+    return false;
+}
+/**
+ * Validate a {@link RecipientStatus} per §1.6.2: the `message` field
+ * MUST NOT exceed 256 UTF-8 bytes, and `state` MUST be one of the
+ * three documented values. Throws on the first violation.
+ */
+export function validateRecipientStatus(s) {
+    if (s.state !== "available" && s.state !== "away" && s.state !== "do_not_disturb") {
+        throw new Error(`recipient_status: invalid state ${JSON.stringify(s.state)}`);
+    }
+    if (s.message !== undefined) {
+        const byteLen = new TextEncoder().encode(s.message).length;
+        if (byteLen > MaxStatusMessageBytes) {
+            throw new Error(`recipient_status: message exceeds ${MaxStatusMessageBytes} UTF-8 bytes (${byteLen})`);
+        }
+    }
+}
+//# sourceMappingURL=ack.js.map

package/dist/delivery/ack.js.map

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

package/dist/delivery/blocklist.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Per-user block list per DELIVERY.md §4.
+ *
+ * The list is server-readable only when explicitly decrypted by
+ * the owning user's authenticated client device. Production
+ * deployments store entries encrypted at rest per §6.3 and unwrap
+ * on demand.
+ *
+ * @module
+ */
+import type { Acknowledgment } from "./ack.js";
+/** Entity kinds per §4.3. */
+export type BlocklistEntityType = "user" | "domain" | "server";
+/** Delivery-time applicability per §4.4. */
+export type BlocklistScope = "all" | "direct" | "group";
+/** One entry in a {@link BlockList}. */
+export interface BlockEntry {
+    id: string;
+    entity: BlocklistEntity;
+    acknowledgment: Acknowledgment;
+    reason?: string;
+    scope: BlocklistScope;
+    /** ISO 8601 UTC. */
+    created_at: string;
+    /** ISO 8601 UTC; absent for permanent blocks. */
+    expires_at?: string;
+    created_by_device_id: string;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Block-list entity. Only the field appropriate for `type` is
+ * populated.
+ */
+export interface BlocklistEntity {
+    type: BlocklistEntityType;
+    /** Required when `type === "user"`. */
+    address?: string;
+    /** Required when `type === "domain"`. */
+    domain?: string;
+    /** Required when `type === "server"`. */
+    hostname?: string;
+}
+/** A user's full block list per §4.1. */
+export interface BlockList {
+    user_id: string;
+    list_version: number;
+    entries: BlockEntry[];
+}
+/** Sender-side identifiers used by {@link matchBlockList}. */
+export interface BlockListSender {
+    /** Full sender address from `brief.from`. */
+    address?: string;
+    /** Verified sender domain from `postmark.from_domain`. */
+    domain?: string;
+    /** SEMP server hostname through which the envelope was routed. */
+    server?: string;
+    /** True when the envelope is part of a group / mailing-list thread. */
+    isGroup?: boolean;
+}
+/**
+ * Return the most-specific entry that matches `sender`, or null
+ * when no entry applies. Entity-type precedence per §4.4:
+ * `user > server > domain`.
+ *
+ * Entries past `expires_at` are skipped (no clock-skew tolerance
+ * applied here — callers that want the §4.4 grace window evaluate
+ * expiry themselves).
+ *
+ * All comparisons are case-insensitive.
+ */
+export declare function matchBlockList(list: BlockList | null, sender: BlockListSender, now?: Date): BlockEntry | null;
+/**
+ * Minimal lookup interface the delivery pipeline consumes at step
+ * 8 of DELIVERY.md §2. Implementations return the recipient's full
+ * block list. Returning null is the canonical "no list configured"
+ * answer and is treated as "no entries match".
+ */
+export interface BlockListLookup {
+    lookup(recipient: string): Promise<BlockList | null>;
+}
+/** Trivial in-memory {@link BlockListLookup} keyed by recipient address. */
+export declare class StaticBlockListLookup implements BlockListLookup {
+    private readonly lists;
+    constructor(lists?: Record<string, BlockList>);
+    lookup(recipient: string): Promise<BlockList | null>;
+}
+//# sourceMappingURL=blocklist.d.ts.map

package/dist/delivery/blocklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocklist.d.ts","sourceRoot":"","sources":["../../src/delivery/blocklist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,6BAA6B;AAC7B,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE/D,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,eAAe,CAAC;IACxB,cAAc,EAAE,cAAc,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,cAAc,CAAC;IACtB,oBAAoB;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,GAAG,IAAI,EACtB,MAAM,EAAE,eAAe,EACvB,GAAG,GAAE,IAAiB,GACrB,UAAU,GAAG,IAAI,CAkEnB;AAgBD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;CACtD;AAED,4EAA4E;AAC5E,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;gBAEnC,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAM;IAO3C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAG3D"}

package/dist/delivery/blocklist.js

@@ -0,0 +1,107 @@
+/**
+ * Per-user block list per DELIVERY.md §4.
+ *
+ * The list is server-readable only when explicitly decrypted by
+ * the owning user's authenticated client device. Production
+ * deployments store entries encrypted at rest per §6.3 and unwrap
+ * on demand.
+ *
+ * @module
+ */
+/**
+ * Return the most-specific entry that matches `sender`, or null
+ * when no entry applies. Entity-type precedence per §4.4:
+ * `user > server > domain`.
+ *
+ * Entries past `expires_at` are skipped (no clock-skew tolerance
+ * applied here — callers that want the §4.4 grace window evaluate
+ * expiry themselves).
+ *
+ * All comparisons are case-insensitive.
+ */
+export function matchBlockList(list, sender, now = new Date()) {
+    if (list === null || list.entries.length === 0) {
+        return null;
+    }
+    const address = (sender.address ?? "").toLowerCase();
+    const domain = (sender.domain ?? "").toLowerCase();
+    const server = (sender.server ?? "").toLowerCase();
+    const isGroup = sender.isGroup ?? false;
+    const RANK_DOMAIN = 1;
+    const RANK_SERVER = 2;
+    const RANK_USER = 3;
+    let bestRank = 0;
+    let bestEntry = null;
+    for (const entry of list.entries) {
+        if (entry.expires_at !== undefined && entry.expires_at !== "") {
+            const exp = Date.parse(entry.expires_at);
+            if (!Number.isNaN(exp) && exp <= now.getTime()) {
+                continue;
+            }
+        }
+        if (!scopeApplies(entry.scope, isGroup)) {
+            continue;
+        }
+        let rank = 0;
+        switch (entry.entity.type) {
+            case "user":
+                if (address === "" ||
+                    (entry.entity.address ?? "").toLowerCase() !== address) {
+                    continue;
+                }
+                rank = RANK_USER;
+                break;
+            case "server":
+                if (server === "" ||
+                    (entry.entity.hostname ?? "").toLowerCase() !== server) {
+                    continue;
+                }
+                rank = RANK_SERVER;
+                break;
+            case "domain":
+                if (domain === "" ||
+                    (entry.entity.domain ?? "").toLowerCase() !== domain) {
+                    continue;
+                }
+                rank = RANK_DOMAIN;
+                break;
+            default:
+                continue; // unknown entity type — forward-compat ignore
+        }
+        if (rank > bestRank) {
+            bestRank = rank;
+            bestEntry = entry;
+            if (bestRank === RANK_USER) {
+                return bestEntry;
+            }
+        }
+    }
+    return bestEntry;
+}
+function scopeApplies(scope, isGroup) {
+    switch (scope) {
+        case "all":
+            return true;
+        case "direct":
+            return !isGroup;
+        case "group":
+            return isGroup;
+        default:
+            // Empty/unknown scope: forward-compat treats as "all".
+            return scope === undefined || scope === "";
+    }
+}
+/** Trivial in-memory {@link BlockListLookup} keyed by recipient address. */
+export class StaticBlockListLookup {
+    lists;
+    constructor(lists = {}) {
+        this.lists = new Map();
+        for (const [k, v] of Object.entries(lists)) {
+            this.lists.set(k.toLowerCase(), v);
+        }
+    }
+    async lookup(recipient) {
+        return this.lists.get(recipient.toLowerCase()) ?? null;
+    }
+}
+//# sourceMappingURL=blocklist.js.map

package/dist/delivery/blocklist.js.map

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

package/dist/delivery/cancel.d.ts

@@ -0,0 +1,60 @@
+/**
+ * SEMP_SUBMISSION cancel / cancel_response wire shapes per
+ * DELIVERY.md §2.7.
+ *
+ * @module
+ */
+import { type QueueRecordState } from "./queue.js";
+import { type SubmissionStep, SubmissionType } from "./submission.js";
+/**
+ * SEMP_SUBMISSION cancel request per §2.7.1 / CLIENT.md §6.6.
+ *
+ * The client identifies the target envelope by `envelope_id`. An
+ * optional `recipient` narrows cancellation to one queue-state
+ * record; an empty / absent `recipient` means whole-envelope cancel
+ * (every still-non-terminal record).
+ */
+export interface CancelRequest {
+    type: typeof SubmissionType;
+    step: "cancel";
+    version: string;
+    envelope_id: string;
+    recipient?: string;
+    /** ISO 8601 UTC. */
+    timestamp: string;
+}
+/** Construct a {@link CancelRequest}. */
+export declare function newCancelRequest(envelopeId: string, opts?: {
+    recipient?: string;
+    nowFn?: () => Date;
+}): CancelRequest;
+/** One entry in {@link CancelResponse.results} per §2.7.2. */
+export interface CancelResult {
+    recipient: string;
+    state: QueueRecordState;
+    /**
+     * Optional human-readable explanation for unusual outcomes
+     * (e.g. "already delivered, cancellation no-op per §2.7.4").
+     */
+    reason?: string;
+}
+/**
+ * Per-record summary returned by the sending server per §2.7.2.
+ *
+ * A no-op (record was already terminal) returns the prior terminal
+ * state without changing it; the caller distinguishes by comparing
+ * `state` to the expected `"canceled"`.
+ */
+export interface CancelResponse {
+    type: typeof SubmissionType;
+    step: "cancel_response";
+    version: string;
+    envelope_id: string;
+    /** ISO 8601 UTC. */
+    timestamp: string;
+    results: CancelResult[];
+}
+/** Construct a {@link CancelResponse}. */
+export declare function newCancelResponse(envelopeId: string, results: CancelResult[], nowFn?: () => Date): CancelResponse;
+export type { SubmissionStep };
+//# sourceMappingURL=cancel.d.ts.map

package/dist/delivery/cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../src/delivery/cancel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EACL,KAAK,cAAc,EACnB,cAAc,EAEf,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,cAAc,CAAC;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yCAAyC;AACzC,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GACpD,aAAa,CAef;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,cAAc,CAAC;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,GAAE,MAAM,IAAuB,GACnC,cAAc,CAYhB;AAID,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/delivery/cancel.js

@@ -0,0 +1,43 @@
+/**
+ * SEMP_SUBMISSION cancel / cancel_response wire shapes per
+ * DELIVERY.md §2.7.
+ *
+ * @module
+ */
+import {} from "./queue.js";
+import { SubmissionType, SubmissionVersion, } from "./submission.js";
+/** Construct a {@link CancelRequest}. */
+export function newCancelRequest(envelopeId, opts = {}) {
+    if (envelopeId === "") {
+        throw new Error("delivery: empty envelope_id");
+    }
+    const r = {
+        type: SubmissionType,
+        step: "cancel",
+        version: SubmissionVersion,
+        envelope_id: envelopeId,
+        timestamp: isoSecond((opts.nowFn ?? (() => new Date()))()),
+    };
+    if (opts.recipient !== undefined && opts.recipient !== "") {
+        r.recipient = opts.recipient;
+    }
+    return r;
+}
+/** Construct a {@link CancelResponse}. */
+export function newCancelResponse(envelopeId, results, nowFn = () => new Date()) {
+    if (envelopeId === "") {
+        throw new Error("delivery: empty envelope_id");
+    }
+    return {
+        type: SubmissionType,
+        step: "cancel_response",
+        version: SubmissionVersion,
+        envelope_id: envelopeId,
+        timestamp: isoSecond(nowFn()),
+        results,
+    };
+}
+function isoSecond(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+//# sourceMappingURL=cancel.js.map

package/dist/delivery/cancel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.js","sourceRoot":"","sources":["../../src/delivery/cancel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAyB,MAAM,YAAY,CAAC;AACnD,OAAO,EAEL,cAAc,EACd,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAoBzB,yCAAyC;AACzC,MAAM,UAAU,gBAAgB,CAC9B,UAAkB,EAClB,OAAmD,EAAE;IAErD,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,CAAC,GAAkB;QACvB,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,iBAAiB;QAC1B,WAAW,EAAE,UAAU;QACvB,SAAS,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC3D,CAAC;IACF,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,KAAK,EAAE,EAAE,CAAC;QAC1D,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AA8BD,0CAA0C;AAC1C,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,OAAuB,EACvB,QAAoB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;IAEpC,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,iBAAiB;QAC1B,WAAW,EAAE,UAAU;QACvB,SAAS,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO;KACR,CAAC;AACJ,CAAC;AAMD,SAAS,SAAS,CAAC,CAAO;IACxB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AACnD,CAAC"}

package/dist/delivery/disposition.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Delivery disposition data per DELIVERY.md §3.2 + CLIENT.md §4.5.7.
+ *
+ * The `delivery-disposition` sync kind is the control signal a
+ * staged device emits to tell the home server whether a held
+ * envelope should advance to the next stage or be suppressed.
+ *
+ * @module
+ */
+/** The literal `kind` string identifying a delivery-disposition sync marker. */
+export declare const DispositionKind = "delivery-disposition";
+/** Disposition decision per CLIENT.md §4.5.7. */
+export type DispositionDecision = "advance" | "suppress";
+/** Recommended reason tags per CLIENT.md §4.5.7. Operators MAY define more. */
+export declare const DispositionReasonSpam = "spam";
+export declare const DispositionReasonAccepted = "accepted";
+export declare const DispositionReasonPolicy = "policy";
+export declare const DispositionReasonOther = "other";
+/**
+ * Payload of a `delivery-disposition` sync marker. Carries the
+ * inner `data` object of the `semp.dev/device-sync` extension when
+ * the extension's `kind` is `"delivery-disposition"`.
+ */
+export interface Disposition {
+    kind: typeof DispositionKind;
+    source_envelope_id: string;
+    disposition: DispositionDecision;
+    reason?: string;
+    device_id: string;
+}
+/**
+ * Validate `d` is structurally well-formed per CLIENT.md §4.5.7.
+ * Does NOT verify authentication; the home server verifies §3.2.5
+ * (session belongs to `device_id`) at receipt.
+ */
+export declare function validateDisposition(d: Disposition): void;
+/** Outcome of aggregating dispositions at one stage per §3.2.3. */
+export type StageOutcome = "advance" | "suppress";
+/**
+ * Apply the §3.2.3 conservative aggregation rule across the
+ * dispositions collected at one stage:
+ *
+ *   - If any disposition is `suppress`, return `"suppress"`.
+ *   - Otherwise return `"advance"` (covers "any advance" and "no
+ *     dispositions at all" via §3.2.4 fail-open on timeout).
+ *
+ * Does NOT itself enforce the §3.2.5 authentication rules; the
+ * caller filters out late or off-stage dispositions before
+ * aggregating.
+ */
+export declare function aggregateDispositions(ds: Disposition[]): StageOutcome;
+/**
+ * Recommended stage timeout per DELIVERY.md §3.2.2. Operators MAY
+ * configure longer windows.
+ */
+export declare const DefaultStageTimeoutMs = 30000;
+/**
+ * One stage's pending-device set inside a {@link StagedHeld}
+ * record per §3.2.2.
+ */
+export interface StagedHeldStage {
+    /** 1-based stage index; lower delivers first. */
+    stage: number;
+    /**
+     * Devices at this stage that the held envelope was wrapped for
+     * and that have not yet emitted a disposition.
+     */
+    pending_device_ids: string[];
+    /** Dispositions collected so far at this stage. */
+    dispositions: Disposition[];
+}
+/**
+ * One envelope held in the staged-delivery queue per §3.2.2. The
+ * envelope itself is NOT stored twice — this record is the
+ * per-stage pointer set the server maintains.
+ */
+export interface StagedHeld {
+    /** `postmark.id` of the held envelope. */
+    envelope_id: string;
+    /**
+     * Ordered list of stages still to deliver. `stages[0]` is the
+     * current pending stage; lower stages have already delivered or
+     * been bypassed.
+     */
+    stages: StagedHeldStage[];
+    /**
+     * Wall-clock time at which the current stage times out (set by
+     * the home server when entering a stage). ISO 8601 UTC. Empty
+     * string means "no deadline set".
+     */
+    deadline: string;
+}
+/**
+ * Whether the wait at the current stage MUST terminate per §3.2.2.
+ * Either every device at the stage has emitted a disposition, or
+ * the deadline has passed.
+ *
+ * Does NOT return the outcome; the caller follows up with
+ * {@link aggregateDispositions} to compute that.
+ *
+ * @param stage - the current stage record
+ * @param now - current wall-clock
+ * @param deadline - ISO 8601 UTC string; empty means "no deadline"
+ */
+export declare function isStageComplete(stage: StagedHeldStage, now: Date, deadline: string): boolean;
+//# sourceMappingURL=disposition.d.ts.map

package/dist/delivery/disposition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposition.d.ts","sourceRoot":"","sources":["../../src/delivery/disposition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gFAAgF;AAChF,eAAO,MAAM,eAAe,yBAAyB,CAAC;AAEtD,iDAAiD;AACjD,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,UAAU,CAAC;AAEzD,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAC5C,eAAO,MAAM,yBAAyB,aAAa,CAAC;AACpD,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAChD,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,eAAe,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,mBAAmB,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,CAuBxD;AAED,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,YAAY,CAOrE;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,mDAAmD;IACnD,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,MAAM,GACf,OAAO,CAyBT"}